Integration Guide

github enterprise logo GitHub Enterprise Integration Jira Server

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 Enterprise 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 Enterprise must at least have Read permissions. This allows them to view commits and smart commits, and browse repositories (if enabled) of connected GitHub Enterprise repositories inside Jira.
fyi
For repository managers, 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 Enterprise to Jira Server

This process requires an existing GitHub Enterprise account.

  1. On your Jira Server dashboard menu, go to Git > Manage Git Repositories.
  2. The git configuration page for connecting repositories is displayed.
  3. On the Auto-connect integration panel, click GitHub Enterprise.
  4. git for jira cloud auto-connect panel - select github
  5. The following screen screen is displayed:
  6. github auto-connect screen - select github enterprise
  7. For the Host URL, enter the address of the GitHub Enterprise server.
  8. Enter login credentials as required.
  9. fyi
    For repository managers, collaborators or users that have enabled 2FA, enter username and the PAT as the password.  For more information on setting up PATs, see Connecting to a GitHub Account with Enabled 2FA.
  10. On the following screen, Git Integration for Jira add-on will read all available repositories from your GitHub account.  Click Import repositories.
  11. fyi
    Repositories that are added or removed from GitHub Enterprise will be likewise connected or disconnected from Jira Server.
    note
    If your git url contains multiple repositories, it will be added as tracked repositories in the git configuration list.  Otherwise, a git repository is added instead.
  12. After the import process, the Settings dialog is displayed:
  13. jira server connect vsts settings dialog
  14. Click Finish.

Working with Branches and Pull Requests with GitHub Enterprise Jira Server

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

The service user must have 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.
    • If there are several repositories with the same name, the listed GitHub repositories will have their names attached with a GitHub organization name.  For example, BigBrassBand/second-webhook-test-repo.
    • 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 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.
  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.

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.
    • If there are several repositories with the same name, the listed GitHub repositories will have their names attached with a GitHub organization name.  For example, BigBrassBand/second-webhook-test-repo.
    • 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, 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 Enterprise web portal.