Skip to content

Integrate gitStream with Jira

gitStream makes it easy to build workflows that link your GitHub repo to your Jira workspace. Automatically update Jira issues, enforce Jira best-practices, and reduce the amount of context switching developers experience by reducing their need to interact with third-party project management tools.

Automation Examples

Label Missing Jira Info

Label PRs that don't reference a Jira ticket in the title or description. This uses regex to detect Jira ticket formats in the title (e.g. ABC-1234), and URLs to Jira tickets in the description.

Label Missing Jira

Configuration Description

Conditions (all must be true):

  • The PR lacks a Jira ticket number in the title, or a link to a Jira ticket in the PR description.

Automation Actions:

  • Apply a missing-jira label.

Label Missing Jira Info

# -*- mode: yaml -*-

manifest:
  version: 1.0

automations:
  label_missing_jira_info:
    # Triggered for PRs that don't have either a Jira ticket number in the title,
    # or a link to a Jira ticket in the PR description.
    if:
      - {{ not (has.jira_ticket_in_title or has.jira_ticket_in_desc) }}
    run:
      - action: add-label@v1
        args:
          label: "missing-jira"
          color: 'F6443B'

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_desc: {{ pr.description | includes(regex=r/atlassian.net\/browse\/\w{1,}-\d{3,4}/) }}
Download this example as a CM file.

Provide automatic links to Jira issues that are associated with PRs.

Automatically Link to the Related Jira Card

Configuration Description

Conditions (all must be true):

  • The PR contains a reference to an Jira card in the title or branch name.

Automation Actions:

  • Post a comment that provides a link to the associated Jira Card.

Automatically Link to the Related Jira Card

# -*- mode: yaml -*-

manifest:
  version: 1.0

provider: jira

# Change this to the name of your Jira organization
orgName: org

{% set ticketid = "" %}
{% for ticket in tickets %}
{% if (ticket | includes(regex=r/.+/)) %}
{% set ticketid = ticket %}
{% endif %}
{% endfor %} 

automations:
  link_jira:
    if:
      - {{ has.ticket_in_title or has.ticket_in_branch }}
    run:
      - action: add-comment@v1
        args:
          comment: Issue Tracker Link - [{{ticketid}}]({{tracker[provider].baseurl}}{{ticketid}})

has:
  ticket_in_title: {{ pr.title | includes(regex=tracker[provider].pattern) }}
  ticket_in_branch: {{ branch.name | includes(regex=tracker[provider].pattern) }}

tracker:
  jira:
    baseurl: https://[orgName].atlassian.net/browse/
    pattern: r/\b[A-Za-z]+-\d+\b/

tickets:
  - {{branch.name | capture(regex=tracker[provider].pattern)}}
  - {{pr.title | capture(regex=tracker[provider].pattern)}}
Download this example as a CM file.

Update Jira Fields When PRs are Created

Automatically update Jira tickets with pull request information. You can modify this to send any PR metadata to Jira.

Jira Webhook Integration Required

You need to configure an incoming Jira webhook to use this automation.

Automatic Jira Updates Automatic Jira Updates

Configuration Description

Conditions (all must be true):

  • A PR is created that contains a Jira ticket reference in the title or branch name.

Automation Actions:

  • Send a webhook to Jira containing metadata to add to the Issue.

Automatic Jira Updates

# -*- mode: yaml -*-

manifest:
  version: 1.0

on:
  - pr_created

{% set ticketid = "\b[A-Za-z]+-\d+\b" %}
{% for ticket in tickets %}
{% if (ticket | includes(regex=r/.+/)) %}
{% set ticketid = ticket %}
{% endif %}
{% endfor %} 

automations:
  jira_update_field: 
    if:
      - {{ has.jira_ticket_in_title or has.jira_ticket_in_branch }}
    run:
      - action: send-http-request@v1
        args:
          url: "{{ env.JIRA_UPDATE_PR_FIELD_WEBHOOK }}"
          method: POST
          headers: '{"Content-type": "application/json"}'
          body: '{"issues":["{{ticketid}}"],"data":{"pr_url":"https://github.com/{{repo.owner}}/{{repo.name}}/pull/{{pr.number}}"}}'

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_branch: {{ branch.name | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}

tickets:
  - {{branch.name | capture(regex=r/\b[A-Za-z]+-\d+\b/)}}
  - {{pr.title | capture(regex=r/\b[A-Za-z]+-\d+\b/)}}
Download this example as a CM file.

Automatically Create Jira Issues for New PRs

Automatically create Jira tickets for new pull/merge requests.

Jira API & Webhook Integration Required.

This automation requires you to connect to the Jira API and incoming webooks.

Required gitStream Plugins

This example requires you to install the hasJiraIssue plugin.

Learn more about gitStream plugins.

Create Jira Issue Create Jira Issue

Configuration Description

Conditions (all must be true):

  • The PR description contains the text - [x] Auto-create Jira Issue
  • No existing Jira issues reference the PRs URL.

Automation Actions:

  • Send an HTTP request to create a new Jira issue.

Automatically Create Jira Issues

# -*- mode: yaml -*-

manifest:
  version: 1.0


###### ** Configure This Section ** ######

# Configure this for your Jira instance and the email associated with your API key.
# You can safely use these values because only your API key is sensitive. 
jiraSpaceName: "my-company" # e.g. my-company.atlassian.net
email: "my.email@example.com"
# If you're concerned about exposing this information,
# we recommend using environment variables for your production environment.

# -----------

# Pass the API token associated with the email above to gitStream via an environment variable.
jiraAuth: {{ env.JIRA_API_TOKEN }}
# Learn more about env: https://docs.gitstream.cm/context-variables/#env

# -----------

# Change this to the Jira field you want to match the input string against.
jiraField: "myField"
# If you want to search a custom field, you should provide the ID like so:
# jiraField: "cf[XXXXX]"
# Replace XXXXX with the ID of the custom field you want to search.
# More information:
# Using JQL to search the Jira API: https://support.atlassian.com/jira-service-management-cloud/docs/jql-fields/
# How to find the ID of a custom field: https://confluence.atlassian.com/jirakb/how-to-find-any-custom-field-s-ids-744522503.html

# -----------

###### ** Automation ** ######
# You may want to update the text in the comment gitStream posts;
# otherwise, this section shouldn't need to be changed.
prUrl: "https://github.com/{{ repo.owner }}/{{ repo.name }}/pull/{{ pr.number }}"
has_jira_issue: {{ prUrl  | hasJiraIssue(jiraAuth, jiraField, jiraSpaceName, email) }}

automations:
  automatic_jira_task: 
    if:
      - {{ not has_jira_issue }}
      - {{ pr.description | includes(regex=r/\- \[x\] Auto-create Jira Task/)}}
    run:
      - action: send-http-request@v1
        args:
          url: {{ env.JIRA_WEBHOOK }}
          method: POST
          headers: '{"Content-type": "application/json"}'
          body: '{"data":{"pr_url": "{{ prUrl }}","title":"{{ pr.title }}"}}'
      - action: add-comment@v1
        args:
          comment: "gitStream automatically created a Jira task for this PR"
Download this example as a CM file.

Update Jira Ticket Status When PRs are Created

Automatically update the status of Jira tickets when a PR is opened.

Jira Webhook Integration Required

You need to configure an incoming Jira webhook to use this automation.

Automatic Jira Status Updates Automatic Jira Status Updates

Configuration Description

Conditions (all must be true):

  • A PR is created that references a Jira ticket in the title or description.

Automation Actions:

  • Make an HTTP request to a Jira webhook that is pre-configured to update the ticket status.

Automatic Jira Status Updates

# -*- mode: yaml -*-

manifest:
  version: 1.0

on:
  - pr_created

{% set ticketid = "\b[A-Za-z]+-\d+\b" %}
{% for ticket in tickets %}
{% if (ticket | includes(regex=r/.+/)) %}
{% set ticketid = ticket %}
{% endif %}
{% endfor %} 

automations:
  jira_change_status: 
    if:
      - {{ has.jira_ticket_in_title or has.jira_ticket_in_desc }}
    run:
      - action: send-http-request@v1
        args:
          url: "{{ env.JIRA_CHANGE_STATUS_WEBHOOK }}"
          method: POST
          headers: '{"Content-type": "application/json"}'
          body: '{"issues":["{{ticketid}}"],"data":{"pr_url":"https://github.com/{{repo.owner}}/{{repo.name}}/pull/{{pr.number}}"}}'

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_branch: {{ branch.name | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}

tickets:
  - {{branch.name | capture(regex=r/\b[A-Za-z]+-\d+\b/)}}
  - {{pr.title | capture(regex=r/\b[A-Za-z]+-\d+\b/)}}
Download this example as a CM file.

Use Slash Commands to Assign Tickets in Jira

Automatically assign Jira tickets based on code review actions.

Jira Webhook Integration Required

You need to configure an incoming Jira webhook to use this automation.

Automatically Assign Jira Tickets Automatically Assign Jira Tickets

Configuration Description

Conditions (all must be true):

  • The PR description contains the slash command: /gitstream assign-jira followed by a Jira username.

Automation Actions:

  • Trigger a Jira webhook to update the assignee field with the username provided in the slash command.

Automatically Assign Jira Tickets

# -*- mode: yaml -*-

manifest:
  version: 1.0

assigneeRegex: r/(?<=\/gitstream assign-jira ).*(?=<br \/>)/

{% set ticketid = "" %}
{% for ticket in tickets %}
{% if (ticket | includes(regex=r/.+/)) %}
{% set ticketid = ticket %}
{% endif %}
{% endfor %} 

automations:
  jira_assign: 
    if:
      - {{ pr.description | includes(regex=assigneeRegex) }}
    run:
      - action: send-http-request@v1
        args:
          url: "{{ env.JIRA_WEBHOOK }}}"
          method: POST
          headers: '{"Content-type": "application/json"}'
          body: '{"issues":["{{ticketid}}"],"data":{"assignee":"{{pr.description | capture(regex=assigneeRegex)}}"}}'

has:
  jira_ticket_in_title: {{ pr.title | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}
  jira_ticket_in_branch: {{ branch.name | includes(regex=r/\b[A-Za-z]+-\d+\b/) }}

tickets:
  - {{branch.name | capture(regex=r/\b[A-Za-z]+-\d+\b/)}}
  - {{pr.title | capture(regex=r/\b[A-Za-z]+-\d+\b/)}}
Download this example as a CM file.

Configure Jira for gitStream Integrations

If you want to build gitStream automations to interact with the Jira API or Jira webhooks, you'll need to complete some setup in Jira, GitHub, and gitStream. This section outlines the setup process depending on the type of automation you want to build.

These guides are for sending HTTP requests to Jira

If the gitStream automations you want to use don't make any HTTP requests to a Jira API or webhook, you can ignore this section.

Use Webhooks to Trigger Jira Automations

Jira automations are the preferred method for gitStream to trigger actions within Jira, so you should use them whenever possible. If webhooks don't provide access to the data you need, or acheive the functionality you want, use the Jira API instead.

First, create a Jira automation that uses an incoming webhook as the trigger and add whatever automation components you want after this trigger. Save the webhook URL in a secure place, you'll need it later.

Here is an example of an automation that uses the webhookData property of the incoming data payload to create a new task. It expects the incoming data payload to contain title and pr_url fields to set the task summary and a pr_url custom field our demo environment already has configured.

Jira Automation Example - Create task from incoming webhook

Learn more about working with incoming webhooks in the Jira docs

Next, in GitHub, create an organization secret to store your Jira webhook URL and pass it to gitStream's env context variable by adding a line to .github/workflows/gitstream.yml inside your repo. Make sure to give this a unique name, such as JIRA_CREATE_ISSUE_WEBHOOK: ${{ secrets.JIRA_CREATE_ISSUE_WEBHOOK }}.

Once finished, you can use the env.JIRA_CREATE_ISSUE_WEBHOOK context variable inside CM files to send HTTP requests to Jira from your GitHub repo. For an example of how to do this, check out the create Jira issue automation.

Connect to the Jira API

The Jira API is useful in situations where you need to retreive data from Jira or need to access capabilities that aren't available via Jira Automations. The Jira API uses an account-based token system that follows a basic auth model; this means you'll need an individual account to connect to Jira's APIs and will pass the account email address and API token in the headers of your API requests.

Here's the process to grant gitStream access to the Jira API:

  1. Create an API token for your Jira account, and give it a unique name. Copy the API token, you'll need it in the next step.
  2. Create a GitHub organization secret to store the token and make the secret available to gitStream's env context variable.
  3. Add env.MY_API_TOKEN to any of your CM automations to access the API token and pass it to plugins and automation actions.

Check out the hasJiraIssue filter plugin for an example of how to use Jira API tokens.

Additional Resources

gitStream is a workflow automation tool that enables you to use YAML configuration files to optimize your code review process. Add context to PRs, find code experts for reviews, and automate the merge process to maximize developer productivity.

Learn More about how gitStream Works.

More Automations can be found on the Automation Library and Integrations pages.