Integrate GitHub.com with Jira Cloud

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

What’s on this page:

• Integrate GitHub.com with Jira Cloud
  • Creating a personal access token
  • Using Git service integration
  • Single git repository integration
  • Setting up GitHub permissions
  • Default repository permission
  • Teams and collaborators
  • Setting up GitHub web links
  • Viewing git commits in Jira Cloud
  • Working with branches and pull requests with GitHub
  • Default Branch
  • Creating branches
  • Creating pull requests
  • More Integration Guides

Creating a personal access token

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

Using Git service integration

This process requires an existing GitHub git repository. A GitHub account with enabled two-factor authentication and configured personal access token is encouraged.

We recommend using the Git service integration panel to connect multiple repositories from your GitHub.com account.

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

   
   

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

   
   

3. For the following screen, click GitHub.com to start integration with this git service.

   
   

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

   
   

5. For this guide, click on the OAuth integration to select it.

   • We recommend the OAuth integration which is outlined like a setup wizard — making it more easier for users to connect GitHub integrations.

   • For PAT integration, however, uses personal access tokens to setup GitHub integrations. Users will have to configure their own PAT from GitHub to use for this setup.

   • For GitHub webhook indexing integration, see this article instead.

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

     
     

     • Custom API Path  –  this is a relative path that starts with “/”. The integration will use the relative REST API path to retrieve the list of tracked repositories. The maximum allowed length is 2000 characters or less.

       To learn more examples, see article Jira Cloud: Working with Custom API Path.

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

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

6. Click Connect to GitHub.com to proceed to the next step.

7. Login to your GitHub account when prompted. When connecting to GitHub.com using OAuth for the first time, the user will be presented with a grant authorization screen.

   
   

   • Grant organization access to an org to also have its repositories listed in the Manage repositories page.

   • IMPORTANT If access is not granted, the repositories within those organizations (and even the orgs themselves) will not show up in the Git Integration for Jira app repositories list. The only way to see these repos/orgs is to return to the GitHub web portal using admin interface and specifically grant such permissions (Profile settings ➜ Developer settings ➜ OAuth Apps).

   • Below are the differences between the three authentication options for GitHub:

     Authentication Method       When are org repositories connected?
     ----------------------------------------------------------------------------
     OAuth                       User should notice and press the "Grant" button
                                 near the org repositories to connect them.
     ----------------------------------------------------------------------------
     PAT                         Org repositories are connected immediately.
     ----------------------------------------------------------------------------
     Username/Password           Org repositories are connected immediately.

   • Click Authorize BigBrassBand to continue.

8. The following page is displayed.

   
   

   • The Git Integration for Jira app will read all available repositories from your GitHub account. Repositories of the logged-in GitHub user can be automatically connected to Jira Cloud. Repositories that are added or removed from GitHub will be likewise connected or disconnected from Jira Cloud.

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

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

9. Click Connect repositories to complete this setup.

The GitHub.com repositories are now connected to Jira Cloud. There will be a slight delay in adding 2FA-enabled repositories compared to others. These will show in the git configuration list eventually.

Single git repository integration

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

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

Single git repository integration (HTTPS)

Single git repository integration (SSH)

Setting up GitHub permissions

We recommend using a “service user” in GitHub (example: “Git-Integration-for-Jira”) to be used to integrate GitHub with the Git Integration for Jira app. This dedicated “service user” will allow the GitHub administrator to set permissions so the app 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 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.

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

   
   

   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:

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

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

   
   

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

Setting up GitHub web links

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

For single repository connections, web link setup is optional. However, git links will become available in Git Commits tab when configured.

For more information on this feature, see Documentation: Web linking.

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 in your Jira instance.

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 GitHub

The Git Integration for Jira Cloud app adds two features on the Jira issue developer panel – Create Branch, and Create Pull/Merge Request. For more information about the developer panel, see the Jira Git integration development panel documentation.

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.

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. Git service integrations support this function where the default branch is acquired from almost all integrations and apply this setting at repository level.

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.

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

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

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

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

The newly-created branch is now listed in the Jira 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 Open Git Integration, click Create pull request. The following dialog is displayed.

Pointers:

1. Select a Repository from the list.

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

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

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

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 pull requests 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).

5. Click Create pull request to complete this process. Follow the link to the PR to setup for review and approval.

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

GitHub.com (this page)

GitLab CE/EE (Git Integration for Jira Cloud)

GitHub Enterprise Server (Git Integration for Jira Cloud)

GitLab.com (Git Integration for Jira Cloud)

Azure DevOps | Visual Studio Team Services (VSTS) (Git Integration for Jira Cloud)

Azure DevOps Server | Team Foundation Services (TFS) (Git Integration for Jira Cloud)

AWS CodeCommit (Git Integration for Jira Cloud)

Gerrit (Git Integration for Jira Cloud)

Bitbucket Cloud (Git Integration for Jira Cloud)

Introduction to Git integration (Git Integration for Jira Cloud)