Jira Cloud and self-hosted setup

Tags: Flow

This is a guide on how to connect your Jira Cloud or Jira self-hosted account to Flow.

When Jira and Flow are connected, Flow receives data from Jira, including:

  • Ticket data such as keys, titles, bodies, and comments
  • User information such as name and email
  • Project names
  • Ticket states, labels, and sprints

If your Jira account is behind a firewall, complete the following before connecting to Flow:

  1. Allowlist our IP addresses over port 443
  2. Use a valid SSL certificate that uses a public certificate authority (CA)
  3. Make sure you have public DNS resolution

Important: Use a service account to create this integration. Learn more about creating a service account.

Who can use this?

 Core
Plus
 
  



Permissions

To connect your Jira account to Flow, the service account must have the following permissions to receive project ticket data and metadata:

  • Permission to access Jira
  • Browse users and groups global permission.
  • Browse projects project permission for each project.
  • Create issues permission for each project
  • If issue-level security is configured, issue-level security permission to view affected issues

Learn more about Global permissions (external site, opens in new tab), Project permissions (external site, opens in new tab), and Issue security schemes (external site, opens in new tab).

Jira permissions are complex, and your instance may have different permissions setups depending on the product and version. Learn more about the API endpoints Flow uses to collect information from Jira to check which other permissions you may need.

Note: By default, on the integration details page and the Ticket projects page, the last updated date is set from the timezone from the Jira user profile of the service account or user who set up the integration. If Flow does not have access to the /rest/api/2/myself endpoint, this time will be listed in UTC.

Version Requirements

Jira version 7.13 or higher

Flow integrates with Jira Cloud, Jira Data Center, and Jira Server. Project data is available from Jira Software and Jira Work Management products. While projects from Jira Service Management will appear on the Ticket projects page, they can't be processed by Flow.

back to top


How to connect with Jira

To connect Flow with Jira:

  1. Click Settings in the top navigation of Flow.
  2. In the left navigation under Integrations, click Integrations.
  3. Click the Add integration button in the top right corner of the Integrations page.
  4. Click Jira Cloud & Self-Managed on the Integration Provider page. 
  5. Choose one of three ways to connect your Jira instance:
    • OAuth establishes a connection to Flow via an application link:

      Note: Flow can only connect via OAuth version 1.0a.

    • Access Token establishes a connection to Flow via an access token.

    • Username/password establishes a connection to Flow with your Jira credentials. We strongly suggest you connect to Jira via OAuth or Access Token.

Important: If you migrate your Jira instance from Jira self-hosted to Jira Cloud, you must create a new integration. Updating your Base URL for your existing integration doesn't update your connection and Flow can't ingest data.

back to top


OAuth

Sometimes browser add-ons can interfere with this connection. If you plan to connect your Jira account via OAuth, we recommend opening Flow in an Incognito window to set up this integration. Flow can only connect using OAuth version 1.0a.

  1. Paste your Jira account's base URL into the Base URL field. It looks something like: https://[your company].atlassian.net.
  2. Click Get Keypair.
  3. If the test is successful, you will be provided the credentials you need for your application link in Jira.
  4. Click the Open button under the first step. This takes you to the page in Jira you need for the next steps. If you're prompted to log in, do so with administration credentials. Learn more about using AppLinks in Jira (external site, opens in new tab).
  5. Copy and paste the following URL into the field under Configure Application Links: https://jira.flow.pluralsight.com. If prompted, select the Application type as Atlassian product to ensure you're using OAuth version 1.0a. Learn more about linking to other applications in Jira (external site, opens in new tab).
  6. An advisory box appears. Confirm the URL is accurate.
  7. Click Continue.
  8. In Jira, enter GitPrime into the Application Name box.
  9. Application type defaults to Generic Application. Leave it as Generic Application.
  10. Do not populate any other fields.
  11. Click Continue.
  12. This takes you to another modal in Jira. Enter the Consumer Key, Consumer Name, and Public Key provided by Flow.
  13. Click Continue. This establishes the application link in Jira. You'll see the application link added to the list.

    Note: All of this information can be found on the modal you've been using to connect Flow to Jira.

    Important: Before proceeding to the next step, make sure you have pop-ups disabled on your browser. The following steps will include a pop-up that will finalize your connection to your Jira account. If you have pop-ups blocked, you'll have to start all over.
  14. Back in Flow, click Test Connection.
  15. On the Jira authorization page, click Allow. This establishes the connection on the Flow side to Jira. After this is done, the page will show success.
  16. Click Next. Then proceed to the Final steps section of this article.

back to top


Connect to Jira via access token

Important: Connecting to Jira via access token only works for Jira Cloud. Flow cannot connect to Jira Data Center or Jira Server via access token.

First, create a personal access token in Jira (external site, opens in new tab).

  1. Once you have your personal access token, return to Flow and fill in the following fields to complete your integration:
    • Email—Enter your email address.
    • Access token—Paste your API token here.
    • Base URL—Enter your Jira URL.

  2. Click Test connection.
  3. Click Next to finalize your integration.

back to top

Final steps

  1. Select the services you want to integrate from Jira. The only option here is tickets. Leave that status toggle set to on. If you disable tickets, Flow doesn't show any data from Jira.
  2. Click Next.
  3. Enter the name you want to give the Jira integration.
  4. Click Create.
  5. A Successfully Created banner displays once the connection is established.

Toggle the Import button to on for each project to import the projects you want to track in Flow. By default, importing for all projects is set to off.

In addition to importing your projects, you can also perform the following actions on this integration:

  • Auto Import all projects - Turning this on auto imports all projects and continues to import new projects if applicable.
  • Pause all imports - This keeps new data from being imported. This does not remove existing data.
  • Refresh - This refreshes all ticket projects and discovers any new projects not already displayed in your Project list.
  • Settings - Click Settings to pause or turn off ticket ingestion. Toggle Ticket Services to off to remove all data associated with this Integration. Pausing this service will pause ingestion of new data.

To view and manage your imported Jira projects:

  1. Click Settings.
  2. Click Ticket projects under Integrations.

To learn more about managing your Projects, see Managing ticket projects. To learn more about managing your new integration settings, see Managing integrations.

back to top


Troubleshooting

If you receive an error message when testing your connection during the setup process, check the following and try again:

  • Confirm that your base URL is correct. 
  • Confirm that your permissions are correct. 

OAuth authentication method:

  • Ensure that all fields are left blank except Application name.
  • Confirm that you checked the box next to Create incoming link.

Access token authentication method:

  • Confirm that you pasted your access token without additional characters or spaces before or after the token.
  • Confirm the email address you provided is the same email address associated with your Jira account.
  • Confirm that you're connecting to Jira Cloud, not Jira Data Center or Jira Server. If you need to connect to Jira Data Center or Jira Server, use an alternate authentication method.

Jira self-hosted

  • Ensure you are using Jira 7.13 or higher.

back to top


If you need help, please contact Pluralsight Support.