Repository access with the GitHub App

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:

The Bitrise GitHub App generates a short-term, temporary token for each build that is triggered via the app. This token has only one permission by default: content:read. This means the build can access the GitHub repository but can't do anything else.

You can extend these permissions so that you can perform other operations during a build. For example, this can enable users to push Git tags from their builds, create custom status reports, put a label on a pull request, or push a new version number.

The exact permissions you can extend depends on your GitHub account:

To extend the permissions:

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.

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:

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: {}

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:

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.

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

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.

To switch: