Skip to main content
4 video tutorials

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 doesDefaultAllowed valuesWho can change itAPI field
URLAddress of the Jira sitenone, requiredA full http(s):// URL. Cloud: https://org.atlassian.net; Server: https://jira.example.comCompany adminjira_config.url
Sign in withShown for on-prem connections only. How Merge Pilot signs its requests to Jira (see below)User name and passwordUser name and password, Personal access tokenCompany adminjira_config.auth_method (basic, bearer)
UsernameThe 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 tokennoneCloud: the account's email address. Server/Data Center: the usernameCompany adminjira_config.username
TokenThe secret for that accountnoneCloud: 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 hostCompany adminjira_config.token (write only; has_token)
Webhook secretAuthenticates the webhooks Jira sends (see The Jira webhook); webhooks that do not carry it are ignorednone, requiredAny string. Leave empty when editing to keep the stored oneCompany adminjira_config.webhook_secret (write only; has_webhook_secret)
Skip TLS verificationAccepts any certificate the Jira server shows. Only for self-hosted instances with self-signed certificatesOffOn, offCompany adminjira_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 bearer on 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 settingValue
URLThe connection's Copy webhook URL: <Application URL>/api/v1/webhooks/tracker/<company slug>/<connection id>
SecretThe connection's Webhook secret (where Jira offers a secret)
EventsIssue: updated and deleted

How the webhook is authenticated​

  • Signed deliveries: Jira sends an X-Hub-Signature header, 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 doesDefaultAllowed valuesAPI field
ProjectJira project where change approval issues are creatednone, requiredA project key (stored in upper case)project_key
Issue typeIssue type of change approval issuesnone, requiredOne of the project's issue typesissue_type
Link typeJira issue link type between a change approval and its work items and earlier change approvalsRelatesOne of Jira's link typeslink_type
PrioritiesThe 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 defaultemptyPolicy priorities (for example low, normal, high; matched ignoring case) and Jira priority namespriority_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 doesDefaultAllowed valuesAPI field
Work item projectsOnly keys of these projects are taken for work items, so text like SHA-256 is never taken for an issueEmpty: Any project in this trackerProject keyswork_item_projects
Key patternA regular expression that finds the keys; its first group is the keyEmpty: keys like PAY-123A regular expression (RE2 syntax). An invalid expression is refused on savework_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 doesDefaultAllowed valuesAPI field
Closing statusesMoving the change approval to one of these approves the merge requestEmpty: doneJira statuses (several)closing_statuses
Rejection statusesMoving the change approval to one of these rejects it and closes the merge requestEmpty: rejected and cancelledJira statuses (several)rejection_statuses
Reopen statusStatus an approved change approval is moved back to when new commits arrive and the change policy reopens change approvalsEmpty: a new change approval is created insteadOne Jira statusreopen_status
Merged statusStatus 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 movedOne Jira statusmerged_status
Cancelled statusStatus an undecided change approval moves to when its merge request is closed without mergingEmpty: it is not movedOne Jira statuscancelled_status
Also cancel superseded approved change approvalsA 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 statusOffOn, offcancel_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 doesAllowed valuesAPI field
To statusThe status the path reachesA Jira status; one path per statustransition_paths[].status
Step: transitionOne workflow transition of the path, in orderA transition name or ID; at least one step per pathtransition_paths[].steps[].transition
Step: fieldsThe fields that transition's screen needsA JSON object, for example {"resolution": {"name": "Done"}}, or emptytransition_paths[].steps[].fields

Templates​

Setting (label in the UI)What it doesDefaultAPI field
Summary templateThe summary of each change approval issue[Change approval] {{vcs_project_name}} - {{vcs_mr_title}}summary_template
Description templateThe description of each change approval issueA "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 titledescription_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):

VariableValue
{{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 sentAPI value
TextThe text as it istext
NumberA number; a value that is not a number fails the change approval's creationnumber
UserA Jira user, looked up by the nameuser
SelectOne option, by its valueselect
Multi-selectOptions, from comma-separated valuesmultiselect
LabelsLabels, separated by commas or spaceslabels
DateA date, YYYY-MM-DDdate
Date and timeA moment, RFC 3339 or YYYY-MM-DD (midnight UTC), sent in Jira's date-time formatdatetime
Raw JSONA JSON template; variables are filled in its strings. It must be valid JSON to be savedraw

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 doesAllowed valuesAPI field
Source (work item field)The field ID on the work itemA Jira field IDfield_mappings[].source_field
Target (change approval field)The field ID on the change approvalA Jira field IDfield_mappings[].target_field
StrategyHow values of several work items are combinedFirst: 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​

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 →

Connect Jira for Change ApprovalsYouTube ↗
Shape the Jira Change ApprovalYouTube ↗
Jira Statuses and Your WorkflowYouTube ↗
Only Eligible People Decide in JiraYouTube ↗