Integration Guide

github logo GitHub Integration Jira Server

Connecting to a GitHub Single Git Repository

This process requires an existing GitHub git repository.  Look for the the GitHub repository URL on the repository project page.

Github repository home

Use this information to connect the GitHub git repository to your Jira server via Git Integration for Jira add-on - dashboard Git menu > Manage repositories > Connect to Git Repositories.

Creating a Personal Access Token

If two-factor authentication is enabled for your GitHub account, you will need to create a PAT to access your git repositories.

Follow the steps outlined in Connecting to a GitHub Account with Enabled 2FA.

Setting Up GitHub Permissions

We recommend using a "service user" in GitHub (example: "GitIntegrationforJira") to be used to integrate GitHub with the Git Integration for Jira add-on.  This dedicated "service user" will allow the GitHub administrator to set permissions so the add-on clones only the desired repositories.

Assign GitHub permissions for team members or collaborators to allow which resources are accessible for service users. This feature is only available in a GitHub Organization.

Default Repository Permission

  1. Login to your GitHub.com account.
  2. Go to Settings.
  3. Under Organization settings, click Member Privileges.
  4. Github default repository permission Choose the default permission level for organization members.  The default repository permission only applies to organization members and not to outside collaborators.  If the default permission is set to None, organization members will need to be given access to repositories using the Teams or Collaborators methods (see below).
  5. Save the changes.

For more information, see Access Permissions on GitHub.

Teams and Collaborators

To give a member additional access, they must be added to a team or make them collaborators on individual repos.

Set default repository permission for the current team:

  1. Open an organization team. (Your org > Team > scroll down to the bottom then click the desired team.)
  2. Click the Repositories tab.
  3. GitHub Manage Repository permissions tab
  4. Set Read, Write or Admin repository access as desired.

Assign members to a team on your GitHub repository:

  1. Create a team in your GitHub Organization.
  2. Invite a member to add it into the team.  An email invitation is sent to that GitHub service user.
  3. Add members to team dialog The service user is then added to the team if the invitation has been accepted.
  4. Click the service user to manage permissions for this member to:
    • Set desired Role for this member.
    • Convert this member to outside collaborator.
    • Give this member access to organization repositories.
    • Remove this member from the team.
  5. Click Manage access to manage repository access for this member.
  6. Manage team repository permission
take note
While users have configured PAT for repository access, users in a GitHub Organization must at least have Read permissions. This allows them to view commits and smart commits, and browse repositories (if enabled) of connected GitHub Organization repositories inside Jira.
fyi
GitHub Organization: For collaborators and commit authors, set these users to have Write permissions. This will allow them to view commits and smart commits, browse repositories and also enables them to create branches and pull requests to specified GitHub git repositories via developer panel of a Jira issue.
note
The user PAT for "Require User PAT" setting should have Write permission.  Otherwise, the user will not be able to use it for branch or pull request creation/deletion.

For more information on organization teams, see GitHub: Organizing Members into Teams.

For more information on inviting collaborators, see Inviting Collaborators to a Personal/Organization Repository.

Connecting GitHub.com Git Repositories to Jira Server

  1. Go to Manage Git Repositories (Dashboard > Git menu) in Jira Server.
  2. Click GitHub in the Auto-connect integration panel.
  3. GitHub.com is selected by default.  Paste the personal access token in the provided field.
  4. On the following screen, Git Integration for Jira add-on will read all available repositories from your GitHub account.  Click Import repositories.
  5. Repositories of the logged-in GitHub user can be automatically connected to Jira Server.  Repositories that are added or removed from GitHub will be likewise connected or disconnected from Jira Server.
  6. After the import process, the Settings dialog is displayed:
  7. jira server connect vsts settings dialog
  8. Click Finish.

There will be a slight delay in adding 2FA-enabled repositories compared to others.  These will show in the git configuration list eventually.

Working with Branches and Pull Requests with GitHub Jira Server

This process requires a GitHub git repository and a PAT with repo scopes.

For GitHub Organization, the user must have the Write permissions and the repo PAT scopes.

  1. On your Jira Server, open a Jira issue.  On the Jira developer panel under Git Source Code, click Create Branch.
  2. The following dialog is displayed:
  3. Jira server issue page create branch dialog
    • 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, the following dialog is displayed instead: jira server issue create branch dlg PAT required
    • Click the link label to setup the PAT.  This will show the Repository Browser listing connected git repositories.
    • jira server repository browser enter user PAT
    • Click the  icons  icon to setup a 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.
  4. Click 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.

GitHub 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 following dialog is displayed:
  4. Jira issue page create pull request dialog
    • 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 and a user PAT isn't configured yet for the selected repository via Repository Browser, the dialog below is displayed instead:

    jira server issue page create pat dialog requiring to setup pat
    If an invalid PAT was configured for the selected repository, the pull request creation process will fail.
  5. 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 GitHub web portal.