Documentation

Before you start

• A self-managed or Dedicated GitLab™ instance (not GitLab.com)
• GitLab administrator access — system hooks are instance-wide, so registering one is an admin action
• Jira administrator access, to install the app and open its configuration screen
• Python 3.6+ to run the setup script. No third-party packages needed — deliberately, so you can read the whole script before running it

Setup, in five steps

1. Install the app from the Atlassian Marketplace.
2. Open Jira Settings → Apps → GitLab (self-managed) configuration. Generate your shared secret, copy the web trigger URL, add your Jira project keys. Treat both the URL and the secret as credentials.
3. Download the setup script — its full source is on that page, so you can read every line before you run it. Run it with --dry-run first to see exactly what it would change, without writing anything. Then run it for real. It asks for the web trigger URL, the shared secret, and a GitLab administrator token — read from a secure prompt, never a flag or an environment variable, and never written to disk or printed.
4. The script makes exactly one write call to your instance and never deletes a hook.
5. Push a commit whose message contains a Jira issue key. Open that issue in Jira — the commit appears in the Development panel.

Verifying it worked

Two places show the truth. In the app: the configuration screen shows ingest health. In GitLab: Admin Area → System Hooks → Edit → Recent Deliveries shows the HTTP status your instance actually received — 200 accepted, 401 means the shared secret doesn't match (regenerate it and re-run the script), 503 means no secret has been generated yet.

Note: once accepted, a commit can take anywhere from a few minutes to a few hours to appear in Jira's Development panel — that's Atlassian's own rendering delay, not a sign of a problem. GitLab's delivery record is the authoritative check, not an empty panel.

Rotating the secret

The setup script is safe to re-run any time. Regenerate the secret on the configuration screen and run the script again — the live hook is repaired automatically.

Troubleshooting

• 401 from the script: the admin token is invalid, expired, or missing the api scope.
• 403 from the script: the token isn't an administrator's — system hooks require admin rights.
• Certificate errors: pass your internal CA with --ca-bundle.
• Commits not appearing: check GitLab's Recent Deliveries first, then the app's ingest health, then allow for Atlassian's rendering delay.
• A commit mentioned an issue that didn't exist yet: nothing is lost — it's retried at least once a day and links within a day of the issue being created. Retrying continues for 14 days of licensed operation; after that it's shown as “expired, never linked” on the configuration screen.
• Licence lapsed: the configuration screen stays fully usable. New events aren't written to Jira until you're licensed again.