Configuring repository access

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:

Each Bitrise app has a primary Git repository. This is where your app's code is stored and this repository is cloned when we start a build. By default, a Bitrise app 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.

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

When running a build of an app 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"