> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/issue-trackers/github.md). # GitHub Issues {% hint style="warning" %} The GitHub Issues integration is currently in **beta**. {% endhint %} 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. {% hint style="warning" %} ### 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](#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](/definitions/developer-effort-ftes/daily-effort-model.md) need that record, so the developer effort model doesn't fully cover work tracked in GitHub Issues. Jira and Linear are unaffected. {% endhint %} ## Before you start * You need the [admin role](/settings/organization/managing-users-and-roles.md) in Swarmia. * GitHub has to be connected for [code hosting](/settings/integrations/code-hosting-platforms/github.md) first. Issue syncing uses that same connection. * GitHub Cloud only. GitHub Enterprise Server isn't supported yet. ## Step 1: Turn on GitHub Issues 1. Go to [issue tracker settings](https://app.swarmia.com/settings/issue-trackers), click **Connect**, and choose **Add GitHub issues**. 2. Tick the organizations whose issues Swarmia should read. 3. 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](https://app.swarmia.com/settings/issue-trackers) 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 {% hint style="warning" %} 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. {% endhint %} 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](/features/metrics/issue-cycle-time.md) 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](https://app.swarmia.com/settings/team/issues), where you can match issues by repository, project, label, or assignee. Read more about [issue ownership](/settings/team/issue-ownership.md).
## 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](/settings/organization/pull-request-data-quality/linking-pull-requests-to-issues.md) 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 1. Go to [issue tracker settings](https://app.swarmia.com/settings/issue-trackers). 2. Click the GitHub organization you want to stop reading. 3. 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.swarmia.com/settings/integrations/issue-trackers/github.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.