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.

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 Settings > Trackers. 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.

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 under 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).

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 Settings > Git, on the GitLab card. 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.

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

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. Test checks the token without saving it; Connect saves it. The card then shows the account and the GitLab server, for example “Connected 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 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.

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