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.
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`.
Pull requests	One pull request per story against a branch your team allowed.
CI	kanman reads check runs and commit statuses. Your CI decides whether a change works, see How kanman checks its work.

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

Connect

GitHub is connected once for the workspace, by an owner or admin. Every team uses this connection for its repositories.

In kanman, open Workspace settings > Connections and open GitHub (in the Tracker step of the team setup, owners and admins can also click Connect on the GitHub card). See Connections for the whole page.
Click Connect GitHub, choose Sign in under How kanman signs in and save.
Click Authorize. 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 connection shows Authorized as with the GitHub account you used.

kanman can reach the repositories that account can reach; inside kanman you then narrow it down per team to the repositories on the team’s Team tab. For GitHub Enterprise Server, enter the server’s Address and a token instead of signing in.

Tip

Sign in 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 and open GitHub. The kanman GitHub App is below the connections. 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 below the connections. 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 comment on it
Issues: read and write	Mirror and update issues
Commit statuses: read and write	Read the commit statuses of your CI
Checks: read	Follow your CI
Metadata: read	Required by GitHub for every App

Each run token gets only these permissions, for one repository.

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 merges only when your CI is green and its independent reviewer approved the change (see Merging); GitHub’s rules apply on top, and kanman cannot bypass them.

We recommend:

Keep branch protection on the branches kanman targets.
Require an approving review from a person if your team wants to approve every merge. kanman waits for it like any colleague.
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 under Team > Repositories, on the Tracker line (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 Team > Repositories page fetches them right away, and Preview pickup shows which issues kanman would pick up now.

Disconnect

Open Workspace settings > Connections, open GitHub, click Disconnect on the connection 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 Team > Repositories 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.