Skip to the content

DocumentationGitLab and Jira

Developer tools

GitLab and Jira

Issues and merge requests from GitLab, issues from Jira

The same as GitHub (GITHUB.md) for GitLab: issues created from a handover, issues, merge requests and commits linked by address or by mentioning the handover (HO-12), and their changes followed. Jira issues are mirrored from handovers: one is created in the connected project and its status is followed.

How it is kept safe. A connection's token is sealed: the API cannot read it back, and only OpsCommand's worker, the one service that calls out, uses it. Every connection is checked with GitLab or Jira before it is used, and a failed check says why. In production the worker calls only public https addresses: a connection naming an internal host is refused before any request.

Webhooks. Each connection has its own webhook token, shown once and kept only as its SHA-256. GitLab sends it as X-Gitlab-Token; Jira's webhook address carries it. A delivery without the right token is refused before it is read, and each delivery is applied once.

What an issue contains. The same as on GitHub: the handover's reference and the fields a developer needs to start, already redacted. Logs, evidence and attachments stay in OpsCommand, and the issue links there.

Connecting GitLab (an organisation's administrator)

  1. In GitLab, open the group Settings → Access tokens and add a token: role Developer, scope api, with an expiry date. Copy it.
  2. In OpsCommand, open Administration → Integrations → GitLab and Jira. Choose GitLab, give the address (https://gitlab.com or your own GitLab), the group (group or group/subgroup) and the token, then Connect. The token is sealed. The connection shows Being checked, then Connected or Check failed with GitLab's reason.
  3. OpsCommand shows a webhook address and a secret token, once. In GitLab, open the group Settings → Webhooks and add the address with that secret token. Tick Issues events, Merge request events and Push events.
  4. On each service, under Repositories, choose GitLab and name its projects (group/…/project).

Connecting Jira Cloud (an organisation's administrator)

  1. In Atlassian, open id.atlassian.com → Security → API tokens and create a token for an account that may create issues in the project.
  2. In OpsCommand, open Administration → Integrations → GitLab and Jira. Choose Jira, give the site (https://your-company.atlassian.net), the project key, the account's e-mail address and the token, then Connect. The token is sealed and checked the same way.
  3. OpsCommand shows the webhook's address once; the address carries the token. In Jira, open Settings → System → WebHooks (a Jira administrator) and add it for Issue: created, updated, deleted, limited by JQL to the project (project = KEY).

New Jira issues are of type Bug and carry the label opscommand. A status in Jira's Done category closes the mirror; its own name (To Do, In Progress, Done …) is shown on the handover.

Proven here, and the owner's acceptance

The worker's contract tests call fakes that answer as GitLab's REST API v4 and Jira Cloud's REST API v3 document. They check the token header, the request shapes (a GitLab issue's title and Markdown description; a Jira issue's fields and its Atlassian Document Format description) and the answers. The API tests send webhook payloads shaped as GitLab and Atlassian document them (apps/api/test/fixtures/gitlab/, …/jira/).

With a real GitLab group and Jira project in staging: connect each as above and see Connected. Create a GitLab issue and a Jira issue from a sent handover. Open a merge request whose description says Closes HO-<n>, merge it, and move the Jira issue to Done. All four show on the handover and on the incident's timeline.