GitHub Issues

If your team keeps its tickets in GitHub Issues, Limn can use them as the workspace’s tracker. There is nothing to type in: Limn reads issues with the same gh sign-in it uses for everything else. It only reads GitHub Issues; it never changes an issue.

#What you need

• Your gh sign-in, which Limn already uses. It must be able to read the repositories that hold the issues.
• For GitHub Projects iterations on This Sprint: the read:project scope, which gh auth login does not give by default. Add it with gh auth refresh -s read:project.

#Set it up

Often you do not need to. A workspace with no tracker chosen uses GitHub Issues by itself when one of its repositories has issues turned on and has linked an issue to a pull request in the last 90 days. Settings then shows the choice as GitHub Issues (detected) and says which repository caused it, for example “Picked automatically: acme/payments uses GitHub Issues.”

1. Open Settings → Integrations. Under Issue tracker, set Provider to GitHub Issues.
2. Save. There are no other fields.

#How pull requests link to issues

Linking is exact: a pull request’s tickets are the issues GitHub says it closes.

• “Fixes #12” or “Closes acme/api#12” in the pull request, including issues in other repositories.
• An issue linked in the pull request’s Development panel.

A bare “#12” is not a ticket, and the title and branch name are not read. You can also add an issue by hand: in the Story check, open Add tickets and paste #12, acme/api#12 or the issue’s link.

#What Limn reads

• For each linked issue: the title, body, state (Open or Closed), issue type, first assignee, sub-issues, the issues it is blocked by, the created and closed dates, and the newest 20 comments.
• Acceptance criteria: the issue’s sub-issues, else a task list in the body, else an “Acceptance criteria” heading. Without any, the whole body is the story and the check works criteria out from it.
• Open points: an “Open points” or “Open questions” section of the body.

The sprint

This Sprint takes the first of these that exists:

1. The current iteration of a GitHub Projects board that holds this workspace’s issues. The page is titled with the iteration’s name and dates.
2. The open milestone due soonest across the workspace’s repositories (never an overdue one).
3. Open issues edited in the reporting window.

#How often Limn reads

Limn reads which issues an open pull request closes when the pull request changes, and about every 30 minutes while it is open. It reads each linked issue about every 30 minutes, and the sprint about every 20 minutes while This Sprint is in use. These reads use your GitHub API allowance, a point or so each. When the allowance runs low, Limn waits rather than fail.

#What Limn writes

One thing, only when you pick it: the assignee. In a ticket’s story view, the assignee is a menu of the people GitHub lets you assign in the issue’s repository, and Unassigned. The person you pick becomes the issue’s only assignee, set as you. Limn does not change an issue’s status or labels: the status in the story view is shown, not changed, and a plan’s draft ticket update can be copied but not written back.

#Troubleshooting

More about how Limn uses your GitHub sign-in: GitHub.