Repository access with the GitHub App

Abstract

The Bitrise GitHub App allows users to connect their Bitrise Workspace to a GitHub account or organization with a GitHub App that provides granular access with increased security and automatic status updates.

Supported for GitHub Cloud users

The Bitrise GitHub app is supported for all GitHub Cloud users. GitHub Enterprise Server users need to create and install a different GitHub app, as described in our GH Enterprise integration guide.

The best way to connect your Bitrise account to your GitHub repositories is by integrating with a GitHub app. The Bitrise GitHub app has a number of features that make integration easier:

The app eliminates the need for an SSH key, a Personal Access Token, and a service credential user. For access, it generates a temporary access token before every build, significantly increasing security.
It provides granular access to your repositories: no need to grant access to an entire GitHub organization, instead select the specific repositories the app can access.
With the app installed, you automatically receive Bitrise status updates directly on GitHub with the GitHub Checks app. No need for configuring status reports separately. Note that while only one GitHub account can be connected to a Bitrise Workspace, GitHub Checks can still be configured for repositories owned by other GitHub accounts.

Connecting via the GitHub App integration

This guide is intended for GitHub Cloud users, including GitHub Enterprise Cloud users, who wish to install the Bitrise GitHub App and connect their Bitrise Workspace to a GitHub account or organization with the app. For GitHub Enterprise Server users, we have a separate guide: Integrating self-hosted GitHub Enterprise Server with Bitrise

You can connect via the GitHub App integration in two ways:

From the Workspace settings page.
When adding a new Bitrise project.

One GitHub App installation per Workspace

As only one GitHub account can be connected to a Workspace, a Workspace is always associated with a single installation of the Bitrise GitHub App. No Workspace can be connected to multiple installations of the Bitrise GitHub App.

However, the GitHub Checks functionality of the app is available for repositories owned by other GitHub accounts.

Connecting a GitHub App from the Workspace settings page

A Bitrise GitHub App installation is tied to a Workspace. You can always install and check its connection from the Workspace settings page.

On the Bitrise main page, select your Workspace from the dropdown menu.
From the navigation menu on the left, select Settings.
On the Workspace settings page, select Integrations.
Select the Git provider tab.
Under GitHub, you can see the GitHub App card with Connect via the Bitrise GitHub App. Click Connect.
If you haven't authorized the Bitrise GitHub App before, you will be prompted for authorization at this point:
You will be prompted to select the GitHub account or organization you want to connect. If you don't find the one you need in the list, you need to install the App to that account or organization first: click the link below the list of accounts.
Once you click the link, you will be prompted to select an account or organization. After selecting one, you will be transferred to the Install & Authorize page.
On the Install & Authorize page, select the access type:
- All repositories: the Bitrise GitHub App will have access to all repositories belonging to the account or organization, including future ones.
- Only select repositories: Select one or more repositories that Bitrise will be able to access. You can add more later but to do so, you will need to reconfigure your repository access on the GitHub App's page.
When done, click Install & Authorize. You will be redirected to the Workspace settings page.

Authorization

If you are not authorized on GitHub to install the app, you can still request the installation. Once a GitHub Admin approves the installation, you can come back and select the App installation from the list.
If you have existing apps with OAuth connection, we recommend switching them over to the GitHub App connection.

Connecting a GitHub App when adding a new project

During the process of adding a new project on Bitrise, you have to select how Bitrise can access your repository. This process allows connecting the project via the GitHub App.

Start the process of adding a new project.Adding a new project
At the Select a repository section, select GitHub App (recommnded) from the Provider dropdown menu.
Click Connect account.
You will be prompted to select the GitHub account or organization you want to connect. If you don't find the one you need in the list, you need to install the App to that account or organization first: click the link below the list of accounts.
Once you click the link, you will be prompted to select an account or organization. After selecting one, you will be transferred to the Install & Authorize page.
On the Install & Authorize page, select the access type:
- All repositories: the Bitrise GitHub App will have access to all repositories belonging to the account or organization, including future ones.
- Only select repositories: Select one or more repositories that Bitrise will be able to access. You can add more later but to do so, you will need to reconfigure your repository access on the GitHub App's page.
When done, click Install & Authorize. You will be redirected to continue adding your new Bitrise projec.

Additional linked repositories via a GitHub App

Each Bitrise project has a primary Git repository. This is where your project's code is stored and this repository is cloned when we start a build. By default, a Bitrise project can't access other repositories.

However, your project might require other repositories. For example, it might have private submodules that it must access during a build. If you use the GitHub App, you can do this via linking additional repositories. The feature is available on both GitHub Cloud and GitHub Enterprise Server.

Other connection methods

If you are not using the Bitrise GitHub App, you can still configure access to additional repositories: Projects with submodules or private repo dependencies.

A linked repository is a repository that a Bitrise project can access using a GitHub App installation but it's not the project's primary repository.

When running a build of a project connected via a GitHub App installation, Bitrise generates a temporary token that, by default, can only access the primary repository. Once an additional repository is linked, the tokens generated for the build can access the additional repository.

To be able to link a repository, all of the following conditions must be met:

The GitHub App is installed to the account or organization that owns the repository on GitHub.
The app installation is enabled for the repository.
The user attempting to link the repository can access the repository on GitHub. If your GitHub user account doesn't have access to a repository, you can't link it on Bitrise.

GitHub Enterprise Server

If you use a GitHub App to connect to a GitHub Enterprise Server instance, the app doesn't check user access. You can link any repository that your GitHub App has access to.

Linking additional repositories

To link additional repositories to a project with an established GitHub App connection:

Open your project on Bitrise with a user that has the Admin role on the project.
On the main page of the project, click on the Project settings button.
On the left, select Integrations and then on the Integrations page, select the Git provider tab.
Find the Git integration status card and click Additional repositories.
In the Enable additional repositories dialog, select the repositories you want to link.

You can link a maximum of 50 additional repositories.

You will see a list of repositories. To see a repository on the list:
- On GitHub Cloud, your GitHub user needs to have access to it. If you use GitHub Enterprise Server, user permissions are not checked.
- The GitHub App installation has access to it.
Disabling repositories

If you already have repositories linked, please note that users who otherwise don't have access to those repositories can disable them but cannot add them back!
When done, click Save changes.

Using a private Step library via the GitHub App

Each Bitrise project has a default Step library: a repository of Steps. If the exact source of a Step is not specified in the configuration, the Bitrise CLI pulls the Step data from the default library.

This library can be a private Step library. To access such a library via the GitHub App, you need to add the Authenticate host with netrc Step as the very first Step which will run in your Workflow:

format_version: "13"
default_step_lib_source: https://github.com/my-private-org/my-bitrise-steplib.git
project_type: ios
workflows:
  example:
    steps:
    - https://github.com/bitrise-io/bitrise-steplib.git::authenticate-host-with-netrc@0:

Note that the Authenticate host with netrcStep has a full source identifier to ensure it is pulled from the official Bitrise Step library, not your private library.

Using the Step requires specifying three inputs: the host, the Git username, and the Git password. The Bitrise GitHub App integration uses token-based authentication: each build receives a one time token under the GIT_HTTP_PASSWORD Environment Variable. This Env Var can be used as the password. The username can't be empty because the Step will fail but it is not used so it doesn't matter what you put there.

format_version: '13'
default_step_lib_source: https://github.com/tothszabi/steplib.git
project_type: ios
workflows:
  example:
    steps:
    - https://github.com/bitrise-io/bitrise-steplib.git::authenticate-host-with-netrc@0:
        inputs:
        - host: github.com
        - username: username
        - password: "$GIT_HTTP_PASSWORD"
    - private-script@1: {}

Running git clone with linked repositories

If you attempt to run git clone or other git commands for a linked repository, your build might fail with an authentication error. This is because the authentication credentials are stored in a local netrc file. This file is automatically generated by the official Git Clone Step.

However, if you use your own script to perform git clone, or you use any other Git command requiring authentication before the Git Clone Step, you need to create the netrc file. You have two ways:

You can do it manually.
You can use the Authenticate host with netrc Step. It should be the first Step of your Workflow.

HTTP URLs

Make sure you always use HTTP URLs when cloning private repository dependencies.

workflows:
  example:
    steps:
    - authenticate-host-with-netrc@0:
        inputs:
        - host: github.com
        - username: "username"
        - password: "$GIT_HTTP_PASSWORD"

Switching from OAuth connection to the GitHub App

If your Bitrise project has an OAuth connection set up to your GitHub account, you can change it to the Bitrise GitHub App at any time without losing any functionality. We strongly recommend doing the switch: with the Bitrise GitHub App installed, you no longer need the service credential user, an SSH key, or a webhook to run Bitrise builds.

Can't switch back

Once you switch a Bitrise project from the OAuth connection to the GitHub App, you won't be able to switch back!

To switch:

Install the Bitrise GitHub App as described in the relevant guide: Connecting a GitHub App from the Workspace settings page.
Open your project on Bitrise with a user that has the Admin role on the project.
On the main page of the project, click on the Project settings button.
On the left navigation menu, select Integrations and go to the Git provider tab.
In the Git integration status section, you can see a blue card with information about GitHub App support. To switch, click Switch to GitHub App.

In this section: