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. 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 links automatically within 14 days once the issue is created.
• Licence lapsed: the configuration screen stays fully usable. New events aren't written to Jira until you're licensed again.