Jira
A Jira connection lets Merge Pilot open change approvals as Jira issues and read their decisions back. It works with Jira Cloud (Cloud) and with Jira Server or Data Center (On-prem). Change approvals go to the Jira connection that is linked to the merge request's VCS connection (see Linked tracker connection).
Connection fields
Open the company's Connections tab, choose Add tracker connection and pick Jira as the Provider. The fields shared by every connection (Name, Deployment type, Active) are described in Connections. The section Jira configuration has these fields:
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| URL | Address of the Jira site | none, required | A full http(s):// URL. Cloud: https://org.atlassian.net; Server: https://jira.example.com | Company admin | jira_config.url |
| Sign in with | Shown for on-prem connections only. How Merge Pilot signs its requests to Jira (see below) | User name and password | User name and password, Personal access token | Company admin | jira_config.auth_method (basic, bearer) |
| Username | The Jira account Merge Pilot acts as (the service account). It also fills the template variable {{tracker_service_account}}, and lets Merge Pilot recognise its own actions in Jira, also when it signs in with a personal access token | none | Cloud: the account's email address. Server/Data Center: the username | Company admin | jira_config.username |
| Token | The secret for that account | none | Cloud: an API token from id.atlassian.com. Server/Data Center: the account's password, or with Personal access token the account's personal access token (Jira Data Center 8.14 and newer). Leave empty when editing to keep the stored one; required again when the URL moves to another host | Company admin | jira_config.token (write only; has_token) |
| Webhook secret | Authenticates the webhooks Jira sends (see The Jira webhook); webhooks that do not carry it are ignored | none, required | Any string. Leave empty when editing to keep the stored one | Company admin | jira_config.webhook_secret (write only; has_webhook_secret) |
| Skip TLS verification | Accepts any certificate the Jira server shows. Only for self-hosted instances with self-signed certificates | Off | On, off | Company admin | jira_config.tls_skip_verify |
How Merge Pilot signs in to Jira:
- User name and password (and every Cloud connection): the Username and Token with HTTP basic authentication.
- Personal access token (on-prem only): the Token alone, as a Bearer token, which is how Jira Data Center accepts personal access tokens. The API refuses
beareron a cloud connection.
Test connection reads the account they belong to.
The Jira webhook
Merge Pilot learns about decisions taken in Jira from a Jira webhook. Create it in Jira (System → WebHooks) with:
| Jira webhook setting | Value |
|---|---|
| URL | The connection's Copy webhook URL: <Application URL>/api/v1/webhooks/tracker/<company slug>/<connection id> |
| Secret | The connection's Webhook secret (where Jira offers a secret) |
| Events | Issue: updated and deleted |
How the webhook is authenticated
- Signed deliveries: Jira sends an
X-Hub-Signatureheader,sha256=followed by the HMAC-SHA256 of the body keyed with the webhook secret. Merge Pilot checks it. - Unsigned deliveries: Jira Server and Data Center versions that cannot sign webhooks authenticate with the secret in the URL instead: add
?token=<webhook secret>to the webhook URL. The connection row shows this hint (Unsigned webhooks: add?token=<webhook secret>to the URL) for on-prem Jira connections. The token is used only when the delivery carries no signature header.
A delivery without a valid signature or token is ignored. The same delivery sent twice is processed once. Lost webhooks are not fatal: Merge Pilot re-checks open merge requests against the tracker regularly.
Tracker settings
The settings drawer (gear icon, Settings) says where change approvals are created and how their statuses decide the merge request. It has four sections. Every setting is changed by a company admin and saved with Save settings; the API is PUT /api/v1/connections/{id}/tracker-settings, with the fields below under their JSON names. Closing the drawer with unsaved edits (Cancel, Escape or a click outside) asks first: Discard changes throws them away.
Pickers list what Jira offers (projects, issue types, link types, priorities, statuses); you can also type a value and press Enter.
Project and types
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Project | Jira project where change approval issues are created | none, required | A project key (stored in upper case) | project_key |
| Issue type | Issue type of change approval issues | none, required | One of the project's issue types | issue_type |
| Link type | Jira issue link type between a change approval and its work items and earlier change approvals | Relates | One of Jira's link types | link_type |
| Priorities | The Jira priority a change approval is created with, by the priority of its change policy. Each row is Policy priority becomes Jira priority. Unlisted priorities keep Jira's default | empty | Policy priorities (for example low, normal, high; matched ignoring case) and Jira priority names | priority_map |
Work items (how issue keys are found in commit messages, titles, descriptions and branch names; keys match whatever their case):
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Work item projects | Only keys of these projects are taken for work items, so text like SHA-256 is never taken for an issue | Empty: Any project in this tracker | Project keys | work_item_projects |
| Key pattern | A regular expression that finds the keys; its first group is the key | Empty: keys like PAY-123 | A regular expression (RE2 syntax). An invalid expression is refused on save | work_item_pattern |
A repository can use another Project, Issue type or Link type than the connection: that is set on the repository's page in Merge Pilot.
Statuses
Change approval statuses are the Jira statuses of the change approval issue itself. Statuses are matched by ID, or by name ignoring case. The pickers list the statuses of the project chosen under Project (pick it first), each once: other Jira projects may have statuses of the same name, such as another Done, that the change approval never reaches. A move that fails (for example to a status its workflow does not reach) shows on the merge request page and in the audit log.
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Closing statuses | Moving the change approval to one of these approves the merge request | Empty: done | Jira statuses (several) | closing_statuses |
| Rejection statuses | Moving the change approval to one of these rejects it and closes the merge request | Empty: rejected and cancelled | Jira statuses (several) | rejection_statuses |
| Reopen status | Status an approved change approval is moved back to when new commits arrive and the change policy reopens change approvals | Empty: a new change approval is created instead | One Jira status | reopen_status |
| Merged status | Status the change approval moves to when its merge request is merged, once it is approved: one still undecided at the merge (an emergency change's review, a merge before approval) stays open and moves here when its review approves it. A standard change's change approval kept as a record moves here on the merge (nobody decides it) | Empty: it is not moved | One Jira status | merged_status |
| Cancelled status | Status an undecided change approval moves to when its merge request is closed without merging | Empty: it is not moved | One Jira status | cancelled_status |
| Also cancel superseded approved change approvals | A change approval that was already approved also moves to the Cancelled status when new commits (a new target branch, a policy change) supersede it, so Jira shows one standing approval per merge request. Off: it stays in its approving status. Either way Merge Pilot comments on it with who approved it, for which commit and why it no longer applies, so the issue alone tells what happened. Needs a Cancelled status | Off | On, off | cancel_approved_superseded |
Transition paths: Merge Pilot moves a change approval with the one transition that leads to the target status. When the workflow needs several transitions, or a transition asks for fields, list them here in order.
| Setting (label in the UI) | What it does | Allowed values | API field |
|---|---|---|---|
| To status | The status the path reaches | A Jira status; one path per status | transition_paths[].status |
| Step: transition | One workflow transition of the path, in order | A transition name or ID; at least one step per path | transition_paths[].steps[].transition |
| Step: fields | The fields that transition's screen needs | A JSON object, for example {"resolution": {"name": "Done"}}, or empty | transition_paths[].steps[].fields |
Templates
| Setting (label in the UI) | What it does | Default | API field |
|---|---|---|---|
| Summary template | The summary of each change approval issue | [Change approval] {{vcs_project_name}} - {{vcs_mr_title}} | summary_template |
| Description template | The description of each change approval issue | A "Change Management Record" in Jira markup listing the project and its path, the merge request with its link, the source and target branches, the author and the title | description_template |
When a template is saved empty, Merge Pilot writes its own summary or description. The summary is made one line and cut to 255 characters, Jira's limit, ending in …. Characters are counted as Jira counts them: an emoji counts as two.
Template variables (written as {{name}}; unknown variables are left as they are):
| Variable | Value |
|---|---|
{{vcs_mr_author}} | MR author username |
{{vcs_mr_author_display_name}} | MR author display name |
{{vcs_random_developer}} | Random project developer username |
{{vcs_mr_title}} | MR title |
{{vcs_mr_url}} | MR web URL |
{{vcs_project_id}} | Project ID |
{{vcs_mr_number}} | MR number |
{{vcs_change_ref}} | MR/PR reference the VCS's way (!12 on GitLab, #12 on GitHub) |
{{vcs_provider}} | VCS name (GitLab, GitHub) |
{{vcs_project_name}} | Project name |
{{vcs_project_path}} | Full project path (group/project) |
{{vcs_commit_hash}} | Short commit hash |
{{vcs_source_branch}} | Source branch |
{{vcs_target_branch}} | Target branch |
{{tracker_mr_author}} | MR author (tracker-mapped username) |
{{tracker_random_developer}} | Random project developer (tracker-mapped username) |
{{tracker_service_account}} | Tracker service account username (the connection's Username) |
{{tracker_work_items}} | Comma-separated work item keys |
{{change_type}} | Change type of the matched policy |
{{priority}} | Priority of the matched policy (normal when the policy sets none) |
{{risk_level}} | Risk level of the merge request (low, medium, high, critical or unknown; empty when its risk was not assessed) |
{{specific_user:username}} | The literal username after the colon |
{{assignee_display_name}} | Display name of the resolved assignee |
{{company_name}} | Company name |
{{date}} | Current UTC date (YYYY-MM-DD) |
"Tracker-mapped" names follow the company's rule for matching people across the VCS, the tracker and Merge Pilot.
Fields
Custom fields are set when change approval issues are created. Each row has a Field ID, a Field value and a Field type. Values can use template variables; the type decides the shape sent to Jira:
| Field type (label in the UI) | What is sent | API value |
|---|---|---|
| Text | The text as it is | text |
| Number | A number; a value that is not a number fails the change approval's creation | number |
| User | A Jira user, looked up by the name | user |
| Select | One option, by its value | select |
| Multi-select | Options, from comma-separated values | multiselect |
| Labels | Labels, separated by commas or spaces | labels |
| Date | A date, YYYY-MM-DD | date |
| Date and time | A moment, RFC 3339 or YYYY-MM-DD (midnight UTC), sent in Jira's date-time format | datetime |
| Raw JSON | A JSON template; variables are filled in its strings. It must be valid JSON to be saved | raw |
An empty value leaves the field out. API field: custom_fields, a map from field ID to { "value", "type" }.
Check with Jira checks the project, issue type and fields above against the change approval create screen, without saving. It reads every page of the create screen's fields, so a screen with many fields is checked whole. It lists problems, or says Jira accepts the settings and how many fields are on the create screen; field IDs are then suggested as you type.
Work item (business task) — Field mappings copy a field value from the linked work items into the change approval issue:
| Setting (label in the UI) | What it does | Allowed values | API field |
|---|---|---|---|
| Source (work item field) | The field ID on the work item | A Jira field ID | field_mappings[].source_field |
| Target (change approval field) | The field ID on the change approval | A Jira field ID | field_mappings[].target_field |
| Strategy | How values of several work items are combined | First: the first work item that has a value. Merge unique: every distinct value, joined with , | field_mappings[].merge_strategy (first, merge_unique) |
A mapped value replaces a custom field value set for the same target. Whether work items are required, their allowed statuses and usage limits are set per change policy.
Saving the settings retries, at the next check, the creation of change approvals that failed with the old settings.
When Jira refuses the assignee
When Jira refuses a person as a new change approval's assignee (User … cannot be assigned issues), the next person who may approve is tried. When Jira refuses them all, the change approval is created unassigned and then assigned with Jira's own assign call. When the Assignee field is not on the create screen, one refused creation is enough: Jira would refuse everyone the same way, so the change approval is created unassigned at once and assigned with Jira's assign call, and its summary (and the template's assignee variables) name that person. When even that fails, it stays unassigned and the merge request says the tracker refused every person who may approve as the assignee (…).
Check with Jira also reports a Description field missing from the create screen (Jira would refuse every change approval) and a missing Assignee field.
How a change approval moves through Jira
- A merge request needs a change approval (a normal or emergency change). Merge Pilot creates an issue in the Project with the Issue type, the templates, the custom fields, the mapped priority and the field mappings, links it to the work items and earlier change approvals with the Link type, and assigns it to someone who may decide it. Jira records the creator as the reporter: the service account, or the change's author when the company asks for that and the author has a Jira account.
- The assignee decides in Jira:
- to a closing status: the change approval is approved;
- to a rejection status: it is rejected;
- out of a closing status to any other status: the approval is withdrawn, when the person may decide the change approval (an approver of the change under Approvals made in the tracker, never its author) or is a company or platform admin. Anyone else's move is undone: Merge Pilot moves the issue back to the first closing status, comments on it and on the merge request, and writes
change_approval_vote_ineligible. Merge Pilot's own transitions (for example moving a change approval back for another approver) do not count.
- The issue is deleted or moved to another key: Merge Pilot no longer counts it, and asks for a new change approval when the policy needs one.
- New commits arrive after approval: depending on the change policy, the issue goes back to the Reopen status, or a new change approval is created.
- The merge request is merged: an approved issue moves to the Merged status. One still undecided (an emergency change's review, or a merge before approval) stays where it is, with a comment that its review is owed, and moves to the Merged status once it is approved (a rejected review stays rejected). It is closed without merging while undecided: the issue moves to the Cancelled status.
The author of a change never decides its change approval.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →