GitHub Enterprise

Using Jira Server or Data CenterSee the corresponding article.

Integrate GitHub Enterprise with Jira Cloud

Quickly learn how to connect GitHub Enterprise git repositories via Git Integration for Jira Cloud.

What's on this page:


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

Creating a Personal Access Token

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

While instructions from GitHub works just fine, follow this article for a quick step-by-step guide to get you started.

Using Auto-Connect

This process requires an existing GitHub Enterprise account. 

We recommend using the Auto-connect integration panel to connect multiple repositories from your GitHub Enterprise account.

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

  2. The git configuration page for connecting repositories is displayed.

  3. On the Auto-connect integration panel, click GitHub Enterprise. The following screen is displayed.

    1. For the Host URL, enter the address of the GitHub Enterprise server.

    2. Enter Username and the paste the PAT on the Token field.

    3. For repository managers, collaborators or users that have enabled 2FA, enter Username and the PAT on the Token field.

  4. Configuring the Advanced settings is optional. However, admins/power users may set how the project listing is displayed.

    1. Custom API Path  –  this is a relative path that starts with "/".  The maximum allowed length is 2000 characters or less.  The integration will use the relative REST API path to retrieve the list of tracked repositories.
      To learn more examples, see article Jira Cloud: Working with Custom API Path.

    2. 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.
      Read about JMESPath expressions on their website. For help with writing expressions, please contact support.
      To learn more examples, see article Jira Cloud: Working with JMESPath Filters.

    3. While Custom API Path and JMESPath filter are mutually exclusive, you can use one, the other, both or neither.

  5. Click Next.

  6. On the following screen, the Git Integration for Jira app will read all available repositories from your GitHub Enterprise account. Click Next.

    • Repositories that are added or removed from GitHub Enterprise will be likewise connected or disconnected from Jira Cloud.

    • 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.

  7. 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 PAT specific for branch and merge requests (via the developer panel» on the Jira issue page).  For more information on this feature, see Integration Settings: Require User PAT ».

    • Set Project Permissions according to your organization's project association rules.

  8. Click Connect.

GitHub Enterprise repositories are now connected to Jira Cloud.

Single Repository

This section is for users who are using SSH connections or those who wanted to only connect a single specific repository.

Obtain the repository URL from the GitHub Enterprise repository project page.  Choose between SSH or HTTPS.

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

  2. Click Connect to Git Repository to open the Connect Wizard.

  3. Paste the URL from GitHub Enterprise web portal in the provided box.

  4. For the login credentials, enter username and user password. For 2FA-enabled accounts, enter username and PAT as the password.

  5. Continue to the next step by following the screen instructions.

  6. Click Finish to complete this process. 

The repository is now connected to Jira Cloud.

Setting Up GitHub Enterprise Permissions

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

Assign GitHub Enterprise 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 Profile > Settings.

  3. On your sidebar, click Organizations.

  4. Click Settings for the selected organization.

  5. On your sidebar, click Member Privileges. The following screen is displayed.

  6. Under the Base permissions, click on the dropdown button.

    • Choose the base permission level for organization members. The base repository permission only applies to organization members and not to outside collaborators. If the base permission is set to None, organization members will need to be given access to repositories using the Teams or Collaborators methods (see below).

  7. 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 > Teams > scroll down to the bottom then click the desired team.)

  2. Click the Repositories tab.

  3. Set ReadWrite 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.

    • The service user is then added to the team if the invitation has been accepted.

  3. Click the service user to manage permissions for this member to:

    1. Set desired Role for this member.

    2. Convert this member to outside collaborator.

    3. Give this member access to organization repositories.

    4. Remove this member from the team.

  4. Click Manage access to manage repository access for this member.

Organization Permissions
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 (if enabled) of connected GitHub Organization repositories inside Jira.

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.

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 ».

The Git Integration for Jira app automatically configures web linking for GitHub Enterprise git repositories.

Viewing Git Commits in Jira Cloud

  1. Perform a git commit by adding the Jira issue key in the commit message. This action 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.

Working with Branches and Pull Requests with GitHub

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

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

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.  Auto-connected integrations support this feature 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 developer panel under Git Integration, click Create branch. 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 GitHub repositories will have their names attached with a GitHub organization name. For example, BigBrassBand/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.

  2. Choose a Base branch.

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

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

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 GitHub repositories will have their names attached with a GitHub organization name. For example, BigBrassBand/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.

  2. Choose the newly-created branch as the Source branch.

  3. Set master as the Target branch.

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

Pull/merge requests are still indexed based on branch name even if the PR/MR 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 GitHub web portal.

More Integration Guides