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 app's repository, Bitrise needs a public-private SSH keypair, with the public key registered to your app'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 an app to Bitrise but you can update your keys at any point. You can even skip SSH key configuration when adding the app and register SSH keys later.

Accessing multiple repositories

If your app 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. However, keep in mind that GitHub does not support this method. To learn more, see Apps 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 app. This is completely optional as Bitrise can generate and automatically register SSH keys for you, either during the process of adding the app to Bitrise or later in the App 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 register your app on bitrise.io, you’ll have to provide the private key.

Configuring SSH keys for your Bitrise app

To configure SSH keys on bitrise.io:

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

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

    app-settings.png
  3. Find the SSH settings section.

  4. Click Change SSH keypair.

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

    ssh_keypair.png
  5. Choose from one of three options:

    • Generate SSH keypair and auto-add it to GitHub: Bitrise automatically registers a public SSH key to your GitHub repository. Choose this if you have administrator rights to the repository.

    • Generate SSH keypair: Bitrise generates an SSH keypair for you, and you have to manually register the public key to your Git repository.

    • Use your own SSH keypair: You provide your own SSH keypair for authentication, and you have to manually register the public key to your Git repository.