Git Integration for Jira Cloud Documentation

Contact support  

Azure DevOps | Visual Studio Team Services (VSTS)

Using Jira Server or Data Center?  See the corresponding article.

Integrate VSTS/Azure DevOps with Jira Cloud

Quickly learn how to connect Azure DevOps/VSTS git repositories via Git Integration for Jira app.

The Git Integration for Jira app supports Azure Repos.

What’s on this page:


Right click here and open this video in a new window/tab for more viewing options.

Creating personal access tokens

If you have not yet generated a personal access token (PAT), you can create one by following the simple steps in this article – use the table of content anchor link to go to the Azure DevOps / VSTS section.

This step is highly required for Azure DevOps/ VSTS integrations connected via the Full feature integrations panel.

Permissions

Set Azure DevOps/VSTS repository permissions according to your organization’s rules. Viewing commits from Jira requires the user to have at least Read or View permissions. For branch/pull request creation, set specific service users with Write permissions.

Git Integration for Jira Cloud requires Git admins to allow the third-party app access OAuth security policy in their organization settings:

  1. On your Azure DevOps/VSTS portal, go to the home page.

  2. Click an organization then go to Organization Settings (sidebar).

  3. Under Security, click Policies.

  4. Ensure that the Third-party application access via OAuth option is set to ON.

For projects connected with Azure Active Directory, set the conditional access policy validation to OFF:

Using Git service integration

Connecting Azure DevOps / VSTS accounts with Full feature integration enables usability features that are not available in single repository connections.

Creating personal access token

If you have not yet generated a personal access token (PAT), you can create one by following the simple steps in this article – use the table of content anchor link to go to the Azure DevOps / VSTS section.

This step is highly required for Azure DevOps/ VSTS integrations connected via the Full feature integrations panel.

Authenticate with OAuth (recommended)

This process requires an existing Microsoft account with Azure DevOps/VSTS git projects.

We recommend using the Git service integration panel to connect multiple repositories from your Azure DevOps/VSTS account.

  1. On the Jira Cloud dashboard menu, go to Apps ➜ Git Integration: Manage integrations.

  2. On the Manage integrations page, click Add integration.

  3. On the following screen, click on the Git service integration panel for your integration type.

  4. The following screen is displayed.

    1. For Git hosting service, scroll to Microsoft using OAuth, select Visual Studio Team Services (VSTS). If you are using Azure DevOps Repos, choose that instead.

    2. Configuring the Advanced settings is optional. This setting is used with integration to retrieve the list of tracked repositories. Set a filter that will only load some cloned repositories which can be viewed in the Manage repositories page. However, admins/power users may set how the project listing is displayed on the following:

    3. JMESPath filter  –  JMESPath is a query language for JSON used to filter API results and to limit which repositories are integrated. The maximum allowed length is 2000 characters or less.

      1. If the field is empty, the Git Integration for Jira app will get all available accounts and then scans all available git repositories.

      2. If the field is not blank, the app will assume it as a single account path and will try to use it. To connect to all available accounts, manually create integrations for each one of them.

      3. Read about JMESPath expressions on their website.

      4. For help with writing expressions, please contact support.

      5. To learn more examples, see article Jira Cloud: Working with JMESPath Filters.

  5. Click Connect Azure Repos/VSTS to continue.

  6. Login to your Microsoft account, if prompted. We recommend creating a new Microsoft user and setting specific permissions for use with Jira Cloud. The following authentication screen is displayed.

  7. The Git Integration for Jira Cloud app will read all available repositories from your Azure DevOps/VSTS git service account. The following screen is displayed.

    1. Currently, all available accounts are scanned and corresponding URLs are created internally. Repositories of the logged-in Microsoft user can be automatically connected to Jira Cloud. Repositories that are added or removed from Azure DevOps/VSTS will be likewise connected or disconnected from Jira Cloud.

    2. Use the search options to filter displayed repositories for the current screen.

    3. Connect all repositories and organizations or select specific repositories to connect for this integration.

  8. Click Connect repositories. For now, only git projects are supported from Azure DevOps or VSTS.

Azure DevOps/VSTS git repositories are now connected to Jira Cloud.

Authenticate with personal access token

This process requires an existing Microsoft account with Azure DevOps/VSTS git projects and PAT is configured.

We recommend using the Full feature integrations panel to connect multiple repositories from your Azure DevOps/VSTS account.

  1. On the Jira Cloud dashboard menu, go to Apps ➜ Git Integration: Manage integrations.

  2. On the Manage integrations page, click Add integration.

  3. On the following screen, click on the Git service integration panel for your integration type.

  4. The following screen is displayed.

    1. For Git hosting service, scroll to Microsoft using PAT, select Visual Studio Team Services (VSTS). If you are using Azure DevOps Repos, choose that instead.

    2. Enter the personal access token on the provided box.

    3. Configuring the Advanced settings is optional. This setting is used with integration to retrieve the list of tracked repositories. Set a filter that will only load some cloned repositories which can be viewed in the Manage repositories page. However, admins/power users may set how the project listing is displayed on the following:

    4. JMESPath filter  –  JMESPath is a query language for JSON used to filter API results and to limit which repositories are integrated. The maximum allowed length is 2000 characters or less.

      1. If the field is empty, the Git Integration for Jira app will get all available accounts and then scans all available git repositories.

      2. If the field is not blank, the app will assume it as a single account path and will try to use it. To connect to all available accounts, manually create integrations for each one of them.

      3. Read about JMESPath expressions on their website.

      4. For help with writing expressions, please contact support.

      5. To learn more examples, see article Jira Cloud: Working with JMESPath Filters.

  5. Click Connect and select repositories to continue.

  6. Login to your Microsoft account, if prompted. We recommend creating a new Microsoft user and setting specific permissions for use with Jira Cloud. The following authentication screen is displayed.

  7. The Git Integration for Jira Cloud app will read all available repositories from your Azure DevOps/VSTS git service account. The following screen is displayed.

    1. Currently, all available accounts are scanned and corresponding URLs are created internally. Repositories of the logged-in Microsoft user can be automatically connected to Jira Cloud. Repositories that are added or removed from Azure DevOps/VSTS will be likewise connected or disconnected from Jira Cloud.

    2. Use the search options to filter displayed repositories for the current screen.

    3. Connect all repositories and organizations or select specific repositories to connect for this integration.

  8. Click Connect repositories. For now, only git projects are supported from Azure DevOps or VSTS.

Azure DevOps/VSTS git repositories are now connected to Jira Cloud.

Single git repository integration

This process requires an existing Azure/VSTS git repository. Look for the the Azure/VSTS repository URL on the repository project page. Choose between SSH or HTTPS.

Use this information to connect the Azure/VSTS git repository to your Jira Cloud via Git Integration for Jira app:

Single git repository integration (HTTPS)

Single git repository integration (SSH)

The repository is now connected to Jira Cloud.

Webhooks fail with DefaultCollection in URL Path
To fix webhooks for old VSTS/Azure repository connections with DefaultCollection in the URL path, update the Repository origin field in the Manage git repositories page ➜Actions ➜ Edit repository settings with the repository URL currently being returned by Azure.

Troubleshooting integration

Some repositories are not showing for the integration user. If this is the case, make adjustments to the configuration on the following settings:

  1. Permissions  –  verify correct permissions have been granted to the integration user.

  2. Grant access to the Git Integration for Jira app.

  3. Convert the current repository format to git.

For detailed information, see Troubleshooting: Repositories missing from Azure/VSTS/TFS integrations.

Webhooks and web linking

The Git Integration for Jira app automatically configures web linking for Azure DevOps/VSTS git repositories.

Webhooks are supported on Azure DevOps and VSTS.
First – configure webhooks in the Git Integration app in Jira via the Apps menu ➜ Git Integration: Manage Git Repositories then click Indexing triggers (sidebar). Enable the feature and save the settings. Then follow these instructions to setup the webhook trigger. Azure DevOps/VSTS webhooks will trigger an immediate index of all repositories within the integration.

For detailed step-by-step guide showcasing webhooks setup, see this article.

Linking Azure DevOps/VSTS git commits to Jira Cloud

This process requires a VSTS/Azure DevOps git repository.

  1. On your web browser, login to your Azure DevOps/VSTS account then go to your working repository.

  2. Clone this repository into your Visual Studio IDE.

    … or update your local repository files by performing a Pull action via VS IDE ➜ Team Explorer.

  3. Create or modify a file from your local repository.

  4. Perform a commit of the changes via Team Explorer ➜ Changes.

    • Enter the commit message by mentioning the Jira issue key to associate this commit to. (Underlined in red).

    • Click the dropdown on the Commit All button then select Commit All and Push.

  5. The commit is now displayed in the specified Jira issue.

Viewing git commits in Jira Cloud

  1. Perform a git commit by adding the Jira issue key in the commit message. This will associate the commit to the mentioned Jira issue.

  2. Open the Jira issue.

  3. Scroll down to the Activity panel then click the Git Commits tab.

  4. Click View full commit to view the code diff.

For more information about this feature, see Documentation: Linking git commits to Jira issues.

Working with branches and pull requests with Azure DevOps/VSTS

This process requires a VSTS/Azure DevOps git repository and a PAT with at least Code (read and write) scope.

This feature allows users to create branches and pull requests while inside Jira.

Default branch

Most git integrations allow changing of the default branch of the repository/project other than "master".  This change is reflected in the Repository Settings of the Git Integration for Jira app on the next reindex. Full feature integrations support this function where Git Integration for Jira app gets the default branch from almost all integrations and apply this setting at repository level. 

Main branch for repositories within an integration can only be changed on the git server.

Creating branches

On your Jira Cloud, open a Jira issue. On the Jira Git integration development panel, click Open Git Integration then click Create branch. The following dialog is displayed.

Pointers:

  1. Select a Repository from the list.

    1. The git host service logo is displayed for all the repositories in the dropdown list to easily identify which git service they belong.

    2. If there are several repositories with the same name, the listed Azure DevOps/VSTS repositories will have their names attached with a Azure DevOps/VSTS organization name. For example, johnsmith/second-webhook-test-repo.

    3. Use the search box in the dropdown list to filter displayed repositories.

    4. OPTIONAL Designate the repository to be the default selected repository for current Jira project. To configure default repositories for more than one Jira project – use the User settings page.

    5. For integration that uses PAT, the user is required to provide a personal access token for the repository to proceed creating the branch. Otherwise, no branch is created.

  2. Choose a Source branch. OPTIONAL Designate the branch to be the default selected branch for the currently selected repository. To configure default branches for more than one repository – use the User settings page.

  3. Enter a Branch name or leave it as is (recommended).

  4. Click Create branch to complete this process.

For more detailed information on this feature, see Create branch.

The newly-created branch is now listed in the developer panel under Branches. Perform a commit to the newly-created branch to be ready for merge.

Creating pull requests

Before you can create a pull request, you need to create a branch first.

The pull request feature works the same as merge request.

On your Jira Cloud, open the Jira issue where your previously created a branch. On the developer panel under Git Integration, click Create pull request. The following dialog is displayed.

Pointers:

  1. Select a Repository from the list.

    1. The selected repository will display the git service logo to identify which git host it is located from.

    2. If there are several repositories with the same name, the listed Azure DevOps/VSTS repositories will have their names attached with a owner/team name. For example, johnsmith/second-webhook-test-repo.

    3. Use the search box to look for the specific repository that will be used.

    4. OPTIONAL Designate the repository to be the default selected repository for current Jira project. To configure default repositories for more than one Jira project – use the User settings page.

    5. For integration that uses PAT, the user is required to provide a personal access token for the repository to proceed creating the branch. Otherwise, no branch is created.

  2. Choose the newly-created branch as the Source branch. OPTIONAL Designate the branch to be the default selected branch for the currently selected repository. To configure default branches for more than one repository – use the User settings page.

  3. Set master as the Target branch.

  4. Enter a descriptive Title or leave it as is (recommended).

Pull requests are still indexed based on branch name even if the PR title does not have the Jira issue key – as long as the branch name contains the Jira issue key.

Preview allows you to see the comparison view of the current changes in the selected Source branch vs Target branch (usually master).

For more detailed information on this feature, see Create pull/merge request.

The pull request is listed on the developer panel of the Jira issue page.

The pull request is also ready for approval by the reviewers in your Azure DevOps/VSTS web portal.

Merging branch to master

Continuing from the above steps, the current branch is ready for merge.

  1. On the Team Explorer, update your local repository by performing a Pull action.

  2. Go to Pull Requests.

    The pending pull request items are displayed here. Pull requests requires the approval of the reviewers before it can be merged from the VS IDE.

  3. Go to Branches. Click Merge. The following screen is displayed.

    • Set the source to the branch to which you pushed the commits.

    • Set the target branch to master.

  4. Click Merge (button) to continue.

The reviewer’s approval is required to completely merge the pull request. This usually takes place in the Azure DevOps/VSTS portal where your updated code is being reviewed.

Once approved, the team leader or reviewer can then complete the merge. The commit can be viewed in the associated Jira issue page.

Have feedback about this article? Did we miss something? Let us know!
On this page