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

Everyone connects their own GitHub account. The account of the admin who sets up a team is the one kanman uses for that team’s repositories.

In kanman, open Workspace settings > Connections and find the Code card (the Connect GitHub or GitLab button in the Tracker step of the team setup leads there too). See Connections for the whole page.
Click Connect on the GitHub row. 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 row shows Connected 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

Without the kanman GitHub App, 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.

kanman GitHub App

With the kanman GitHub App installed, runs no longer use your personal connection to work on the code. For every clone, push and pull request kanman gets a short-lived token from GitHub that works for exactly one repository, the one the run works on, and expires after an hour.

Open Workspace settings > Connections. The kanman GitHub App is under the GitHub row on the Code card. You need to be a workspace owner or admin.
Click Install kanman GitHub App. GitHub opens.
Choose the organization or account and the repositories kanman may work on, then confirm. GitHub asks you to sign in so kanman can check that you may install the App there.
GitHub sends you back to Workspace settings > Connections, and the installed account is listed under the GitHub row. Install on another account adds one more.

The App asks GitHub for these permissions:

Permission	Why
Contents: read and write	Clone the repository and push the run’s branch
Pull requests: read and write	Open the pull request and post the evidence pack
Issues: read and write	Mirror and update issues
Commit statuses: read and write	Set the `kanman/outcome-gate` status
Checks: read	Follow your CI
Metadata: read	Required by GitHub for every App
Variables: read	Read the CI variables named in .kanman/verify.json

Each run token gets only the permissions in the first six rows, for one repository. The variables permission is used separately, only to read the names your verify manifest lists.

Repositories whose owner has not installed the App keep using your GitHub connection. If kanman says the App is not available, runs also keep using your GitHub connection. To stop using the App, click Remove next to the account under the GitHub row; to uninstall it on GitHub as well, open Settings > Applications > Installed GitHub Apps in GitHub.

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 Repositories and tracker, on the Tracker card (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 on the team’s Repositories and tracker settings page fetches them right away, and Preview pickup shows which issues kanman would pick up now.

Disconnect

Open Workspace settings > Connections, open the ⋯ menu on the GitHub row, choose Disconnect and confirm; the confirmation says what stops. 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 on the team’s Repositories and tracker settings page.
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.