Connect Jira and GitLab

Many teams plan in Jira and keep their code in GitLab. kanman supports this combination: stories come from a Jira project, code changes go to GitLab as merge requests, and GitLab pipelines are the CI kanman checks every change with.

You can also combine Jira with GitHub code, or use GitLab issues as the tracker. The rules below are the same.

A team that started on its own kanman board can connect Jira, GitHub or GitLab later and link its existing stories instead of copying them. See Use kanman without a tracker.

Jira

What kanman does with Jira

The kanman user

kanman acts in Jira as a normal user, so you can see in Jira’s history what it did. We recommend a dedicated Jira account, for example [email protected] with the display name “kanman”, with access to the project and permission to browse, create, edit, transition and comment on issues.

Connect

Jira is one of the systems on Workspace settings > Connections (see Connections). Owners and admins connect it there, or right inside the team setup: Connect on the Jira card of its first step opens the same form in place.

1. Choose where your Jira runs:
   • Jira Cloud: your site URL, for example https://acme.atlassian.net, the email address of the kanman user and an API token of that user. Create the token in the Atlassian account under Security > API tokens.
   • Jira Data Center: the address of your Jira, for example https://jira.acme.de, and a personal access token of the kanman user, created in the Jira profile under Personal Access Tokens.
2. For a Jira Data Center that only your company network reaches, turn on Reach it through our runner. kanman’s cloud then never contacts your Jira: your self-hosted runner does every read and write. In a workspace that runs everything on its runners, this is always the case.
3. Select Connect. kanman stores the token as a secret of your workspace (it is never shown again), then tests the connection and shows what it may use: issues, sprints, comments and, on Jira Cloud, Jira Product Discovery. Through the runner, the test runs as soon as your runner is online.

Without the runner, your Jira must be reachable from the internet over https.

When you set up a team on this connection, the Project and repositories step offers the projects of your Jira as suggestions. Pick the project key, and kanman reads the project’s workflow statuses, uses them as the team’s columns and maps each to a role. The dry run at the end of the setup shows the result.

Changes in Jira reach kanman within a few minutes. For instant updates, a Jira administrator adds a webhook for issue and comment events under System > WebHooks, with the URL and secret kanman gives you. kanman rejects webhook deliveries without a valid signature.

What kanman may do in Jira

On the team’s page Team > Connections, the Jira entry lists everything kanman can change in Jira, with one setting each: Off, Ask first or Automatic.

Nothing changes on its own when you connect: what kanman already did for the team stays Automatic, anything new starts Off. Mentions from people without access to the team never become work.

If you lower an action to Ask first, kanman asks in the team’s chat (“May I do this in Jira? Move SBX-12 to review”) and acts after one tap on Yes, do it. When a person causes the change themselves, for example by approving stories or moving a story on the board, their action counts as the approval. Only the team’s heads change these settings, and what the Jira user may not do, or what your workspace limits, cannot be chosen. Every change kanman makes is recorded in the team’s activity with a link to the issue.

Besides changing issues, kanman can read your Jira when it plans and answers: issues and their history, comments, the active and next sprints, releases and, on Jira Cloud, ideas in Jira Product Discovery. It reads only, and what it reads never counts as an instruction.

Map statuses to column roles

Jira statuses differ per project. The team setup maps each status to one of kanman’s roles for you: by its name first, then by its Jira status category (see Columns), and shows the result in the dry run. You change it on the Tracker line of Team > Repositories (Change in the dry run takes you there once the team exists), where Suggest roles fills the roles from the status names again. The settings show the mapping as a diagram: each Jira status with an arrow to the step of kanman it leads to, and beside it kanman’s steps with how many statuses lead there; a step no status leads to is marked with a warning.

Boards with German status names are mapped like this by default:

Other common names are recognized too, for example “Zu erledigen” (backlog), “Bereit zur Entwicklung” (ready), “In Prüfung” (review) and “Erledigt” (done). Check the mapping in the dry run. A status without a role is left alone: kanman never moves an issue into it.

Work both ways

On the Tracker line of a team with Jira (Team > Repositories), two more settings decide how kanman and your Jira project work together.

Pick-up from Jira. Choose what brings an issue to kanman:

• Statuses: an issue that enters one of the chosen statuses.
• Labels: an issue that gets one of these labels.
• Mentions: a team member writes @kanman in a comment. Only people who are members of your workspace and whose Jira account is mapped to them on the Jira connection count; mentions by anyone else never become instructions.

kanman reads the issue, decides whether to take it and says so on the issue in a short comment in its own words, before it starts: “I’ll take this; plan: …” or “Not taking this because …”. When it takes the issue, it creates a story and links it to the issue. Each status, label or comment brings an issue to kanman once. Issues that are linked to a story already follow that story instead.

Use Test with an issue to check the rule on one issue key before you rely on it. The test only reads the issue: nothing is saved, commented or started.

Jira follows the story. For each step of a story (Ready, In progress, Review, Done) pick the one Jira status the issue moves into, or Don’t move. kanman moves the issue only into the status you picked. Done waits until the merge is verified. The merge request and the browser proof are added to the issue as links.

Every comment kanman writes in Jira ends with a line that marks it as written by AI. Picking up by status and label needs the Jira webhook described above; mentions also arrive without it, within a few minutes.

GitLab

What kanman does with GitLab

Connect

GitLab is connected once for the workspace, by an owner or admin, under Workspace settings > Connections: open GitLab and click Connect GitLab. Every team uses this connection for its repositories. Choose how kanman signs in:

• gitlab.com: choose Sign in, save, and click Authorize; confirm in GitLab, and the connection shows Authorized as with your GitLab account. An access token works for gitlab.com too.
• Your own GitLab: enter the Address of your GitLab, for example https://gitlab.acme.de, and an access token as Token or key.

Reached from kanman’s cloud, your GitLab server must be reachable over https from the internet, like Jira. A GitLab that only your company network reaches connects through your runner.

The token can be a personal, group or project access token. It needs the api scope, so kanman can clone, push the run branches, open merge requests and read pipelines. Why not only write_repository: besides pushing, kanman opens and updates merge requests, reads their pipelines and approvals, answers review threads and merges when your team lets it, and GitLab allows these only with api. The coding tool never gets the token: it works on a local copy, and kanman pushes. Prefer a project or group access token with an expiry date. Test connection checks the connection and shows what kanman may do with it; a connection whose token expired is marked Needs attention.

Connect through the runner

For a GitLab that only your company network reaches, choose Your runner (inside your network) under Reached from when you connect it. kanman’s cloud then never contacts your GitLab. Your workspace’s own self-hosted runner does all the work with the token: cloning, pushing, merge requests, reviews, merges and everything kanman reads from GitLab, and Test connection checks the token on the runner. If no runner is online, the test waits until one is. In a workspace that runs everything on its runners, connections are always reached from the runner.

1. Open Workspace settings > Connections, open GitLab and click Connect GitLab.
2. Enter the Address of your GitLab and the token as Token or key.
3. Choose Your runner (inside your network) under Reached from and save.

Which account to use. We recommend a service account of the GitLab group the team works in (a group access token, or a personal access token of a service account user):

Reading from your GitLab during a run. The coding tool never gets the token. When it needs to read from your GitLab during a run, for example to fetch private modules, it reads through your runner, which only allows reading. You do not need a separate read token for this.

Repositories. kanman’s cloud cannot list the projects of a GitLab connected through the runner. In the team setup, type the path of each repository instead, for example platform/payments/api.

If your runner was started with its own GITLAB_TOKEN, the connection takes its place; the runner’s token is only used when no connection exists. For the whole setup of a GitLab inside your network, see GitLab behind a VPN or firewall.

Pick the repositories

In the team setup, choose GitLab as the code host in the Project and repositories step when your tracker is Jira. kanman lists the projects your GitLab account can reach. Pick them from the list or type their path, for example platform/payments/api; subgroups are supported. The team’s repositories are saved as GitLab repositories, and kanman clones and pushes them on your GitLab server.

You can add repositories later under Team > Repositories. New repositories use the team’s code host.

Self-managed GitLab

kanman works with self-managed GitLab instances the same way as with gitlab.com. Connect with an access token and the address of your instance as described above. Connected directly, your instance must be reachable from the internet over https. If it is only reachable inside your network, connect it through the runner; GitLab behind a VPN or firewall describes the whole setup.

Checks and merging work on your instance the same way: kanman reads the pipeline result of the merge request, the independent reviewer posts its review on it, and kanman merges when both pass. Links in kanman point to your instance.

Protected branches and approvals

GitLab’s protected branches and merge request approval rules apply to kanman like to everyone else. Allow pushes to kanman/* branches, and keep the target branch protected.

Troubleshooting