Connect GitHub | kanman documentation

GitHub is kanman’s most complete integration. One connection covers both sides of the work: GitHub Issues as the tracker, and the repository where kanman opens pull requests and waits for your CI.

What kanman does with GitHub

Area	What happens
Issues	kanman mirrors the issues of the tracker repository that carry the pickup label (`kanman` by default). Approved stories from intake are created as issues with that label. Evidence packs are posted as issue comments.
Pickup	An issue is picked up when it has the pickup label and sits in the status mapped to the Ready role.
Branches	Each run works on its own branch, for example `kanman/sbx-12-export-invoices`. Acceptance specs are kept on a branch `kanman/spec/<KEY>`.
Pull requests	One pull request per story against a branch your team allowed, with the evidence pack as a comment.
CI	kanman reads check runs and commit statuses. A green CI is part of the outcome gate. kanman also sets its own commit status `kanman/outcome-gate`.

kanman does not delete repositories, branches it did not create, or issues.

Connect

You need to be a workspace admin.

In kanman, open Settings > Git (the Connect GitHub or GitLab button in the Tracker step of the team setup leads there too).
Click Connect on the GitHub card. GitHub opens.
Review the requested access and click Authorize. If your organization restricts third-party access, an organization owner has to approve kanman for the organization.
GitHub sends you back to kanman, and the card shows “Connected as” with your GitHub user name.

The connection uses your GitHub account. kanman can reach the repositories that account can reach; inside kanman you then narrow it down per team to the repositories in the team’s settings.

Tip

Connect with an account that only has access to the repositories your teams need, for example a dedicated machine user. Access the account never has cannot be misused.

Permissions

GitHub shows the requested scopes before you confirm. kanman asks for:

Scope	Why
`repo`	Clone repositories, push the run’s branch, mirror and create issues, open and comment on pull requests, read checks and commit statuses
`workflow`	Push branches in repositories that contain GitHub Actions workflows
`read:user`	Show which account is connected

Runs clone and push with the connection’s token. It is handed to git as a header, never written into URLs, and removed from logs. See Sandbox and secrets.

Coming in a later release

A GitHub App with per-repository, short-lived tokens for each run.

Branch protection and reviews

Your rules apply to kanman exactly as they apply to everyone else. If main requires one approving review and green checks, a kanman pull request needs the same. kanman’s own merge policy can only add restrictions; it cannot bypass GitHub’s.

We recommend:

Keep branch protection on the branches kanman targets.
Add kanman/outcome-gate as a required status check. Then a pull request whose outcome gate has not passed cannot be merged in GitHub either.
Use a CODEOWNERS file if certain areas need specific reviewers.
Keep CI required. kanman waits for it anyway, and required checks make the result visible in GitHub too.

Labels and status

The pickup label is set in the team settings under Tracker (Pickup label). It is created in the repository the first time kanman uses it.
GitHub Issues have no status field. kanman uses one label per mapped status, for example Ready or In Progress. Moving a card in kanman swaps the status label; Done closes the issue. A closed issue without a status label counts as Done.
Changes in GitHub reach kanman within a few minutes. Sync now in the team’s Tracker settings fetches them right away, and Preview pickup shows which issues kanman would pick up now.

Disconnect

Open Settings > Git and click Disconnect on the GitHub card. To remove kanman’s access on the GitHub side too, revoke it under Settings > Applications > Authorized OAuth Apps in GitHub. Teams that use the connection cannot sync or run until you connect again. Existing issues, branches and pull requests stay in GitHub.

Troubleshooting

Symptom	Likely cause
A repository cannot be used	The connected GitHub account has no access to it, or your organization has not approved kanman.
Stories are not written to the tracker	Issues are turned off in the repository (common for forks). Turn them on under Settings > General > Features.
An issue is not picked up	It lacks the pickup label, or its status label is not mapped to the Ready role. Check Preview pickup in the team’s Tracker settings.
A run waits for CI forever	No workflow runs on the run’s branch. Check the `on:` triggers of your workflows; they should include `pull_request`.
kanman cannot push	Branch protection rules apply to all branches, including `kanman/`. Allow pushes to `kanman/` or exclude them from the rule.