GitHub Issues
Learn how to turn on GitHub Issues for a GitHub organization Swarmia already syncs code from.
The GitHub Issues integration is currently in beta.
If Swarmia already syncs code from your GitHub organization, there's nothing new to install. GitHub Issues use the same GitHub App connection, so you choose which organizations Swarmia reads issues from.
After that, Swarmia syncs your issues, sub-issues, and project boards, and shows them next to the commits and pull requests that delivered them.
Known limitations
Status comes from one project. If an issue sits on several GitHub Projects, only one of them decides its status. See issues on more than one project.
Assignment history isn't supported yet. Swarmia syncs an issue's current assignee, not the record of who it was assigned to and when. Assigned in-progress days need that record, so the developer effort model doesn't fully cover work tracked in GitHub Issues. Jira and Linear are unaffected.
Before you start
You need the admin role in Swarmia.
GitHub has to be connected for code hosting first. Issue syncing uses that same connection.
GitHub Cloud only. GitHub Enterprise Server isn't supported yet.
Step 1: Turn on GitHub Issues
Go to issue tracker settings, click Connect, and choose Add GitHub issues.
Tick the organizations whose issues Swarmia should read.
Click Enable — the button names how many organizations you picked.
The first sync covers issues updated during the past two years. Pull request and code syncing are unaffected, whichever organizations you pick.
Step 2: Choose which repositories sync issues
Open the organization from issue tracker settings to reach its settings page. The rest of the setup happens there.
Swarmia reads issues from every repository in the organization. To leave one out, untick it in the Repositories card.
Click Save repositories to apply your changes.
A repository you untick keeps syncing pull requests and code. Only its issues stop appearing in Swarmia, and they come back when you tick it again.
Step 3: Map issue statuses
Swarmia reads an issue's status from the Status field of the GitHub Project the issue sits on. It has to be the single-select field named Status that GitHub Projects creates by default. The Swarmia GitHub App also needs read access to your organization's projects. Without it, issues still sync, but they have no status history and issue cycle time stays empty.
Map each Status option to a Swarmia status in the Status mapping card. An option you leave unmapped counts as to do and never starts the issue's cycle time. A Status option you just added in GitHub can take a few hours to appear.
An issue that's closed in GitHub counts as done whatever its board says, and one closed as not planned counts as won't do.
Issues on more than one project
Swarmia reads status from a single project per issue. If an issue sits on several projects, the project it was added to most recently decides its status, and the Status values on the other projects are ignored.
For example, an issue is added to Platform roadmap in March and you move it to In progress. In July someone adds the same issue to Q3 planning, where it lands in Backlog. Swarmia reports the issue as to do, because Q3 planning took it on last.
The issue's status history and its issue cycle time come from that same project, so moves on the other projects don't register. If that project's Status option is unmapped, the issue counts as to do even when another project maps it to in progress.
Swarmia skips projects that are closed in GitHub, and it skips archived cards. So to give status back to an older project, remove the issue from the newer project or close it in GitHub.
Step 4: Assign issues to teams
A team's issues show up in Swarmia only after the team owns them. Assign them in Settings → Team → Issues, where you can match issues by repository, project, label, or assignee. Read more about issue ownership.
Linking pull requests to issues
Swarmia picks up GitHub's own link between a pull request and the issue it closes, and it reads issue references from the pull request itself. See linking pull requests to issues for every way a link is detected.
Keeping the data up to date
Swarmia keeps GitHub Issues in sync automatically. Webhooks bring changes over within minutes, and a background sync re-checks every repository weekly in case a webhook is missed.
Turning GitHub Issues off
Go to issue tracker settings.
Click the GitHub organization you want to stop reading.
Scroll to the bottom of the page and click Turn off.
Swarmia stops reading issues, sub-issues, and boards for that organization. Your other organizations, your pull requests, and the GitHub App itself stay untouched.
The issues Swarmia already synced are kept, so turning them back on doesn't need a new backfill.
Last updated
Was this helpful?