vsts logo VSTS/Azure DevOps Integration jira server

Connecting to VSTS/Azure DevOps jira server

The Git Integration for Jira add-on supports Azure DevOps.

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

  1. On your Jira Server dashboard menu, go to Git > Manage repositories.
  2. The git configuration page for connecting repositories is displayed.
  3. On the Auto-connect integration panel, click Microsoft.
  4. On the following screen, select Visual Studio Team Services (VSTS).
      or select Azure DevOps from the list, if you have it instead.
    • Enter your personal access token (PAT) on the provided field.
    • take note
      In your VSTS/Azure repository account setting, the PAT should be set to All accessible accounts. As for the Selected scopes:
      • Code (read)  –  This scope allows only to view commits and smart commits, and browse repositories (if enabled) of connected VSTS/Azure repositories inside Jira.
      • Code (read and write)  –  This scope has the Code (read) functions plus the ability to create branches and pull request to specified VSTS/Azure repositories via developer panel of a Jira issue.
      helpful tip
      If you have not yet generated a personal access token (PAT):
      1. Go to your VSTS/Azure repository then navigate to your Account > Security.
      2. On the left sidebar, select Personal access tokens then click Add.
      3. Enter a descriptive name for your PAT. Since this is a connection to Jira, you can name it for example, git-integration-for-jira.
      4. Select desired expiration.
      5. For Accounts, we recommend to set it to All accessible accounts.
      6. On the Authorized Scopes, choose the scope that this token will authorize for your specific tasks (see the note above).
      7. Click Create Token to finish creating your PAT.
      When you're done, make sure to copy and save the token. This token can be used as your password.
    • Click Connect to continue.
    • Configuring the Advanced settings is optional.  However, admins/power users may set how the project listing is displayed on the following:

      • JMESPath filter  –  JMESPath is a query language for JSON used to filter API results and to limit which repositories are integrated.  For help with writing expressions, please contact support mail icon.
      • Read about JMESPath expressions on their website opens in new tab/window.

        The maximum allowed length is 2000 characters or less.

        Example: value[?contains(name, 'git') || contains(name, 'test')] | {value:@}.

        This is a filter based on text in the repository name. It will list all the repositories that contain the specified names. Do note that the declared string format is case-sensitive.


        Currently, all available accounts are scanned and corresponding URLs are created internally.

        Azure DevOps:

        If the field is empty, the Git Integration for Jira app will get all available accounts and then scans all available git repositories.
        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.
  5. Login to your Microsoft account, if prompted.
  6. On the following dialog, Git Integration for Jira add-on will read all available repositories from VSTS/Azure DevOps. Click Import repositories.
  7. Repositories of the logged-in Microsoft user can be automatically connected to Jira Server.  Repositories that are added or removed from VSTS/Azure DevOps will be likewise connected or disconnected from Jira Server.
  8. After the import process, the Settings dialog is displayed:
    • On the Integration Settings, setting the Require User PAT option to ON, will require users to provide a PAT specific for branch and pull requests (via the developer panel on the Jira issue page). The recommended Selected scopes setting for this is Code (read and write).  For more information on this feature, see Integration Settings: Require User PAT icons.
    • Set Smart Commits and Repository Browser to enable/disable these features.
    • Set Project Permissions according to your organization's project association rules.
  9. Click Finish.  For now, only git projects are supported from VSTS or Azure DevOps.
Webhooks are supported on Azure DevOps and VSTS.  First - enable webhooks in the Git Integration app in Jira via the Git menu > Manage Git Repositories then click Webhooks.  Enable the feature and save the settings.  Then follow these instructions to setup the webhook trigger.  Azure DevOps and VSTS webhooks will trigger an immediate index of all repositories within the integration.

Configure Webhooks for VSTS/Azure DevOps

Webhooks are supported on VSTS/Azure DevOps.  You can setup a webhook via Git menu > Manage Git Repositories then click Webhooks.  Enable it to use this feature.  It will trigger immediate index of repositories but will index all of them.

Linking VSTS/Azure DevOps Git Commits to Jira Server

This process requires a VSTS/Azure DevOps git repository.

  1. On your web browser, login to your VSTS/Azure DevOps account then go to your working repository.
  2. Clone this repository into your Visual Studio IDE.
  3. ... or update your local repository files by performing a Pull action via VS IDE > Team Explorer.
  4. Create or modify a file from your local repository.
  5. 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.
  6. The commit is now displayed in the specified Jira issue.

Working with Branches and Pull Requests with VSTS/Azure DevOps Jira Server

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

  1. On your Jira Server, open a Jira issue.  On the Jira developer panel under Git Source Code, click Create Branch.
  2. The Create Branch dialog is displayed.
    • Select a Repository from the list.
    • Choose a Base branch.
    • Enter a Branch name or leave it as is (recommended).
    If the Require User PAT option icons  is enabled in the Integration Settings and a user PAT isn't configured yet for the selected repository via Repository Browser:
    • Click the link label to setup the PAT.  This will show the Repository Browser listing connected git repositories.
    • Click the  icons  icon to setup a valid PAT for the selected repository.  Paste a valid PAT of the current user to proceed.  Invalid PATs will fail the branch creation process.
    • Click  icons  to use this PAT and save it to the current user profile. Click  icons   to cancel setting up PAT for this repository.
    • After the above steps have been taken, the users will be able to proceed with branch creation.
  3. Click Create Branch.  The newly-created branch is now listed in the developer panel under Branches.
  4. On your VS IDE, go to Team Explorer and perform a Pull action.  This will update your local repository with a new branch list.
  5. Go to Team Explorer > Branches.
  6. Under Active Repositories, expand the remote/origin folder view.
  7. Right click the new branch then select Checkout.  The new branch will be listed in the active repositories list.
  8. Make changes to a file to prepare it for commit and branch merge.
  9. On the Team Explorer, click Changes.
    • Make sure that Branch: displays the name of the newly-created branch.  If not, select it again from the list.
    • Add the Jira issue key to the commit message. (Underlined in red).
    • This will associate the commit to the mentioned Jira issue key.
    • Click the dropdown on the Commit All button then select Commit All and Push.

The commit is pushed to the new branch and is now ready for merge.

Pull Request

The pull request feature works the same as merge request.

To create a pull request and merge it to the main source (master):

  1. On your Jira Server, open the Jira issue where your previously created a branch.
  2. On the developer panel under Git Source Code, click Create Pull Request.
  3. The Create Pull Request dialog is displayed.
    • Select Repository from the list.
    • Choose the newly-created branch as the Source branch.
    • Set master as the Target branch.
    • Enter a descriptive title or leave it as is (recommended).

    If the Require User PAT option icons is enabled in the Integration Settings and a user PAT isn't configured yet for the selected repository via Repository Browser:

    Configure a valid PAT for the selected repository. Otherwise, the pull request creation will fail.

  4. Click Create to create the pull 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 VSTS/Azure DevOps 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.
  3. 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.
  4. Go to Branches.  Click Merge.
  5. The following screen is displayed:
    • Set the source to the branch to which you pushed the commits.
    • Set the target branch to master.
  6. Click Merge to continue.

The reviewer's approval is required to completely merge the pull request.  This usually takes place in the VSTS/Azure DevOps 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.


« Table of Contents