Jira and GitLab issue sync: fields, backlog and first-pair setup

Choose the workflow you actually need

GitLab's native Jira integrations can reference Jira issues, show development activity and trigger certain transitions. Use those for that job. If a team keeps standalone GitLab issues while another team works in Jira, write down which fields must stay aligned between those two records.

The Keelcroft app connects one Jira Cloud project to one GitLab project. It handles plain GitLab issues, not every GitLab work-item type. It is not a promise of arbitrary many-to-many project synchronization.

Access and privacy checks before setup

You need Jira installation/configuration permissions and a GitLab token with the api scope, held by a user with at least Maintainer rights for the project. Scope alone does not grant webhook-management rights. On GitLab.com Free, use a personal access token; project access tokens require Premium or Ultimate.

Enter credentials directly in the app. Choose a test project and nonsensitive issues. Confidential GitLab issues are blocked from export by default. Opting in does not reproduce GitLab's audience in Jira or set Jira issue security, and does not erase any earlier copy.

Configure one pair first

1. Save the instance and namespace/project connection in the Jira project's app settings.
2. Store the token and run the setup check. Read every access, webhook and disposable-test cleanup result.
3. Select field directions and review the binary opened/closed status mapping. If several Jira statuses map to one GitLab state, the first configured reverse match is used.
4. Enable sync and link one existing Jira issue to one existing GitLab issue.
5. Edit a title or mapped field in Jira and independently read the GitLab result. Repeat in reverse and inspect the reconciliation result.

If you later enable managed workflow labels, review their explicit mapping and migration constraints before linking a backlog. They are not GitLab's native custom statuses.

Add fields, comments and files deliberately

The public release supports formatted descriptions/new comments, explicit assignee maps, priority labels and selected additional field mappings. Images become links; not every Markdown extension is preserved. A milestone must already exist. Start dates require GitLab 19.1 or later; weight requires Premium or Ultimate.

New comments and note-referenced uploads can copy after linking when enabled. Historical comment edits, deletions and old files are not a full migration archive. File copies are bounded to 10 MiB each and three per direction/pass. Downloads are buffered and are not malware-scanned. Restricted/internal notes are excluded, but you must still review destination visibility.

Preview the backlog, then verify delivery

Use the separate import controls to preview open/all issues, labels and a bounded batch. Review selection before starting. Import dispatch being complete is not proof that every counterpart was created and verified. Cancellation stops pending work, not an already-started write, and does not delete created issues.

A scheduled sweep can recover missed changes for existing linked pairs; it does not discover every unlinked issue, and a five-minute schedule is not a five-minute completion SLA. Watch failures and validate your first imported pairs independently before expanding the rollout.

Decide using your own test result

Proceed only if the app covers your required scope and your first real test works. Check the Marketplace calculator for the licensed Jira site size; the number of people in the connected project is not necessarily the billing tier. A standard evaluation is not a paid subscription or a completed rollout.

Reference: GitLab's native Jira integration feature matrix. This guide describes Keelcroft's public foundational workflow and states candidate/live-testing boundaries separately; it is not a competitor benchmark or certification.