About repository access
To run builds, Bitrise CI must be able to access a Git repository: when a build starts, we create a virtual machine and clone your repository on it, which requires authentication.
To run builds, Bitrise CI must be able to access a Git repository: when a build starts, we create a virtual machine and clone your repository on it, which requires authentication. Bitrise can authenticate to the Git repository in one of three ways:
-
GitHub app: Bitrise provides a GitHub app for both GitHub Cloud and GitHub Enterprise.
-
SSH keys: Create a public and private key, and register the public key at your Git provider, allowing Bitrise to authenticate when running builds.
-
Personal access token: Generate a personal access token at your Git provider and register it at Bitrise. You can use this for HTTPS authorization.
You configure repository access when adding a new project but you can change every setting, including the authentication method and the repository URL itself, later.
There are two ways to select a repository when adding a new project:
-
Manually pasting a repository URL.
-
Connect your Bitrise account to a Git provider account. This allows you to select from a list of available repositories when adding a new project.
Selecting a repository URL is not final: you can always change it later.
If you connect your Bitrise account to a Git provider account, authentication depends on the connection type:
-
The GitHub app uses short-lived access tokens and therefore doesn't require either an SSH key or a personal access token.
-
The OAuth connection requires either an SSH key or a personal access token, depending on the repository URL.
GitHub app
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.
HTTPS URL required
The GitHub App requires an HTTPS URL for your repository instead of an SSH one. Normally, you don't have to worry about this: setting up the GitHub App connection changes the URL of your project. If there's an issue, you can change the URL manually: Changing the repository URL.
Repository access with the GitHub app is configured differently for GitHub Cloud and GitHub Enterprise users.
OAuth connection
An OAuth connection allows a third-party application to access a user's data on a service without sharing their login credentials. On Bitrise, an OAuth connection means connecting your Bitrise account to your Git provider account.
Bitrise supports an OAuth connection with three Git providers: GitHub, GitLab, and Bitbucket. With an OAuth connection, Bitrise can:
-
Retrieve and display a list of the available repositories when adding a new project.
-
Automatically register webhooks. Webhooks allow setting up build triggers and enable the use of Git Insights.
To set up an OAuth connection, check out: OAuth connection.
SSH key authorization
If your repository URL is an SSH URL and you use an OAuth connection, you can authorize Bitrise with SSH keys.
SSH key authorization requires a public and private SSH key. The public key is registered to your Bitrise project's Git repository. Information encrypted with the public key requires the private key, registered at Bitrise, to be decrypted.
You can add an SSH key pair when adding a new project on Bitrise or you can configure them later at the Project settings page. You have the option to:
-
Auto-add a generated SSH key to your repository: Bitrise automatically registers a public SSH key to your GitHub repository. Choose this if you have administrator rights to the repository.
-
Copy a generated SSH key to your Git provider manually: Bitrise generates an SSH keypair for you, and you have to manually register the public key to your Git repository.
-
Add your own SSH key: You provide your own SSH keypair for authentication, and you have to manually register the public key to your Git repository.
Set up SSH key authorization: Configuring SSH keys.
HTTPS authorization
If your repository URL is an HTTPS URL and you use an OAuth connection, you can authorize Bitrise with a personal access token.
HTTPS authorization requires a personal access token for private projects. You create the token at your Git provider and register it at Bitrise.
For most projects with OAuth connection, we recommend SSH URLs and SSH key authorization. We recommend using HTTPS URLs only for public projects: those can't have SSH keys.
Set up HTTPS authorization: Configuring HTTPS authorization.