Skip to content

README.md

Latest commit

 

History

History
74 lines (41 loc) · 4.86 KB

README.md

File metadata and controls

74 lines (41 loc) · 4.86 KB
title Integrate gitStream with Jira
description Use gitStream to implement code review workflow automations for Jira.

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

--8<-- "docs/automations/integrations/jira/label-missing-jira-info/README.md:example"

Automatically Link PRs to Related Jira Issues

--8<-- "docs/automations/integrations/jira/link-jira/README.md:example"

Update Jira Fields When PRs are Created

--8<-- "docs/automations/integrations/jira/jira-update-field/README.md:example"

Automatically Create Jira Issues for New PRs

--8<-- "docs/automations/integrations/jira/create-jira-issue/README.md:example"

Update Jira Ticket Status When PRs are Created

--8<-- "docs/automations/integrations/jira/jira-change-status/README.md:example"

Use Slash Commands to Assign Tickets in Jira

--8<-- "docs/automations/integrations/jira/jira-assign/README.md:example"

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.

!!! tip "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 secret and pass these to gitStream's env context variable by adding lines to .github/workflows/gitstream.yml inside your repo. Make sure to give these a unique name, such as JIRA_CREATE_ISSUE_WEBHOOK: ${{ secrets.JIRA_CREATE_ISSUE_WEBHOOK }} and JIRA_CREATE_ISSUE_SECRET: ${{ secrets.JIRA_CREATE_ISSUE_SECRET }}.

Once finished, you can use the env.JIRA_CREATE_ISSUE_WEBHOOK and env.JIRA_CREATE_ISSUE_SECRET context variables 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

--8<-- "docs/snippets/general.md"

--8<-- "docs/snippets/automation-footer.md"