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 count as CI in the outcome gate.

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

Workspace owners and admins connect Jira under Workspace settings > Connections, on the Trackers card (see Connections). The team setup leads there too: Connect Jira in its first step opens the page, and Continue team setup takes you back with your choices kept.

On the Trackers card, click Connect Jira (or Add a Jira site for another site). The form opens in a panel:

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 Server or 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. Select Test connection. kanman signs in with the token and shows the account it will act as.
3. Select Save connection. The token is stored encrypted and is never shown again. To replace it, save the form again.

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 and uses them as the team’s columns. The next step maps them to roles.

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.

Map statuses to column roles

Jira statuses differ per project. In the Columns step of the team setup (later on the Tracker card of Repositories and tracker in the team settings), you map each status to one of kanman’s roles. kanman suggests a mapping from the status names (Suggest roles in the team settings). 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 suggestion before you confirm. A status without a role is left alone: kanman never moves an issue into it.

GitLab

What kanman does with GitLab

Connect

Connect GitLab under Workspace settings > Connections: on the Code card, click Connect on the GitLab row. Each person connects their own account; the account of the admin who sets up a team is the one kanman uses for that team’s repositories. A panel offers two ways:

• gitlab.com: select Connect gitlab.com and confirm in GitLab, or use an access token as below.
• Your own GitLab, or gitlab.com with a token: enter the address of your GitLab, for example https://gitlab.acme.de, and an access token. Leave the address empty for gitlab.com.

Cancel closes the panel without connecting.

In kanman Cloud, your GitLab server must be reachable over https from the internet, like Jira. A GitLab that only your network can reach works with Run everything on your runners: clones, pushes, merge requests and pipeline checks then happen on your runners, with the runner’s own GITLAB_TOKEN and GITLAB_API_URL.

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 agent never gets the token: it works on a local copy, and kanman pushes. Prefer a project or group access token with an expiry date; kanman shows its scopes and expiry and reminds you before it runs out. Test checks the token without saving it; Connect saves it. The GitLab row then shows the account and the GitLab server, for example “Your connection as kanman on gitlab.acme.de”.

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 Repositories and tracker in the team settings. 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. Your instance must be reachable from the internet over https, so kanman can reach its API and clone over https. If it is only reachable inside your network, see GitLab behind a VPN or firewall.

The outcome gate works on your instance the same way: kanman reads the pipeline result of the merge request, sets the kanman/outcome-gate commit status, posts the evidence comment on the merge request and, when your policy allows it, merges. 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