Skip to main content

Configuring repository access

Abstract

To take full advantage of all the features Bitrise offers, including automatic webhook registration, you need to connect your GitHub/GitLab/Bitbucket account to your Bitrise account.

Bitrise needs access to your code in a Git repository to be able to build. We recommend connecting your Git provider account to Bitrise for this and we offer two main methods of doing so:

  • The Bitrise GitHub App: We strongly recommend using the GitHub App to connect your Bitrise account to GitHub. The app offers increased security and granular repository access. Using the app means you don't need SSH keys or webhooks. This works on the Workspace level: you connect a Workspace to a single GitHub account or organization.

  • OAuth application to the Git provider that allows access to all repositories on the account. This means connecting your personal Bitrise account to a Git provider account. This method is supported for GitHub, GitLab, and Bitbucket.

You can connect all three Git provider accounts by either:

  • Connecting the account when adding a new app.

  • Connecting the account from your Account settings page.

One account per Git provider

Please note that you cannot connect two accounts from the same Git provider (for example, two GitHub accounts) to Bitrise.

Connecting one Git provider account is not final. You can disconnect an account and connect a different one at any time: Linked the wrong Git account to Bitrise.

GitHub App integration

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.

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.

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 the relevant guide.

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

One GitHub App installation per 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.

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.

  1. On the Bitrise main page, select your Workspace from the dropdown menu.

  2. From the navigation menu on the left, select Settings.

  3. On the Workspace settings page, select Integrations.

  4. Select the Git provider tab.

  5. Under GitHub, you can see the GitHub App card with Connect via the Bitrise GitHub App. Click Connect.

    github-app-card.png
  6. If you haven't authorized the Bitrise GitHub App before, you will be prompted for authorization at this point:

    authorize-checks.png
  7. 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.

    install-the-app.png
  8. 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.

  9. 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 app's page.

    authorizing-app.png
  10. 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.

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

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

  1. Start the process of adding a new app.

  2. At the Select a repository section, select GitHub App (recommended) from the Provider dropdown menu.

    select-repository.png
  3. Click Connect account.

    connect-github-app.png
  4. 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.

    install-the-app.png
  5. 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.

  6. 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 app's page.

    authorizing-app.png
  7. When done, click Install & Authorize. You will be redirected to continue adding your new Bitrise app.

Connecting a Git provider with OAuth when adding an app

Connecting a Git provider account with an OAuth app allows Bitrise to:

  1. Log in to your bitrise.io account.

  2. Click the + symbol on the top menu bar and select Add New App on the web UI.

    Adding a new app from a CLI

    You can also add a new app using CLI. For more information, check out Adding a new app from a CLI.

  3. On the Create New App page, select the account and set the app’s privacy setting.

  4. Use the radio buttons under the Select repository section to choose between selecting a remote repository or entering an URL manually.

    If you opt to enter a git URL manually, add it in the Git repository (clone) URL field and click Next.

  5. Choose the Git service provider of the app’s repository, if you chose to select a remote repository. If no account with that provider has been connected to your Bitrise account, the UI will display the option to connect.

    select_git_repo.png
  6. Click Connect account. This will take you to the login page of the Git provider.

  7. Log in to the Git provider account.

  8. You should be prompted to authorize bitrise.io - do it! If successful, you should be redirected to Bitrise, and a pop-up message should inform you that you successfully linked the account. Click Okay.

Connecting a Git provider with OAuth from the Account settings page

Connecting a Git provider account with an OAuth application allows Bitrise to:

  1. In the upper right corner, open the account selector dropdown menu.

  2. Select the Account settings option.

    account-settings.png
  3. On the left, under Connected Git providers, click the toggle next to the name of the Git provider you wish to connect.

    Connect account to Bitrise
  4. Log in to the Git provider account.

  5. You should be prompted to authorize bitrise.io - do it! If successful, you should be redirected to Bitrise, and a pop-up message should inform you that you successfully linked the account. Click Okay.

Disconnecting a Git provider account

  1. In the upper right corner, open the account selector dropdown menu.

  2. Select the Account settings option.

    account-settings.png
  3. On the left under Connected Git providers, click the toggle next to the name of the Git provider you wish to disconnect.

Switching from OAuth connection to the GitHub App

If your Bitrise app 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 an app from the OAuth connection to the GitHub App, you won't be able to switch back!

To switch:

  1. Install the Bitrise GitHub App as described in the relevant guide: Connecting a GitHub App from the Workspace settings page.

  2. Open your app on Bitrise with a user that has the Admin role on the app.

  3. On the main page of the app, click on the App Settings icon: settings.svg.

    app-settings.png
  4. On the left navigation menu, select Integrations and go to the Git provider tab.

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

    switch-to-github-app.png