Skip to main content

Configuring SSH keys

Abstract

To access your app's repository, Bitrise needs an SSH key. You can add an SSH key when you first add an app to Bitrise but you can update your keys at any point in App settings.

SSH keys are the primary method of authentication. To access your project's repository, Bitrise needs a public-private SSH keypair, with the public key registered to your project's Git repository.

There is one exception to this: if you use the Bitrise GitHub App to connect your Bitrise Workspace to GitHub, you do not need an SSH key.

Using an HTTPS URL

You can use HTTPS Git URLs, using a personal access token for authorization: in this case, you don't need an SSH key: Configuring HTTPS authorization.

You can add an SSH key when you first add a project to Bitrise but you can update your keys at any point. You can even skip SSH key configuration when adding the project and register SSH keys later.

Accessing multiple repositories

If your project needs to access multiple repositories during the build, the best practice is to generate an SSH keypair, and register the public key to every repository you need. Alternatively, you can create a machine user and register the SSH key to that user. To learn more, see Projects with submodules or private repo dependencies.

Generating your own SSH keypair

You can always generate your own SSH keypair on your own device and use the generated public and private keys for your Bitrise project. This is completely optional as Bitrise can generate and automatically register SSH keys for you, either during the process of adding the project to Bitrise or later in the Project settings menu.

Generate your own SSH keypair with a simple Command Line/Terminal command:

ssh-keygen -t rsa -b 4096 -P '' -f ./bitrise-ssh -m PEM

This generates two files in the current directory (the directory where you run the command):

  • bitrise-ssh (private key)

  • bitrise-ssh.pub (public key)

Copy and paste the public key to your Git hosting service (for example, GitHub), and when you add your project on bitrise.io, you’ll have to provide the private key.

Configuring SSH keys for your Bitrise project

To configure SSH keys on bitrise.io:

  1. Open your project on Bitrise with a user that has the Admin role on the project.

  2. On the main page of the project, click on the Project settings button.

    project-settings-button.png

  3. On the left, select Integrations and then select the Git provider tab.

  4. Find the Repository authorization credentials section.

  5. Next to the SSH key, click Replace.

    If you haven't had an SSH key added before, the button will show Add SSH keypair instead.

    ssh_keypair.png

  6. Choose from one of three options:

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

  7. Click Save changes.

In this section:

A project on Bitrise represents a Git repository that stores source code and has been connected to Bitrise to be able to run builds on it. As such, a Bitrise project isn't necessarily an actual mobile application: it's just the code on which you run builds with Bitrise.