If you have a project with one or more submodules or other private repository dependencies (for example, CocoaPods repositories), Bitrise needs access to all repositories or submodules for a successful build. Bitrise uses SSH to access Git repositories of private apps: to grant access, you need to make sure all the repositories can be accessed with the public SSH key generated for your Bitrise app.
There are two ways to achieve this:
- Register the same SSH key for every repository you have to access during the build.
- Register the SSH key with a bot user and add that user to all repositories.
Registering the same SSH key for every repository is the best, most secure way - but not all services support it. GitLab and Bitbucket does support it, GitHub, however, doesn’t. If your code is stored on GitHub, read on!
We’ll go through the other option, using a bot user or machine user - GitHub calls them machine users - in detail. In brief, the concept is simple: you register the Bitrise public SSH key to a user and add that user to all repositories that have to be accessed for your Bitrise build.
GitHub itself recommends this method for accessing multiple repositories. Let’s quickly go through an example. If you already understand the concept and just need the step-by-step guide to get it done, go to the Using a machine user to access private repositories section.
Using a machine user to access private repositories ⚓
A machine or bot user is a GitHub user that is not used by humans, instead it is exclusively used for automation. This is the best way to access a private repository: you create a machine user, add a public SSH key to the user, and then provide the user read access to the repository.
Adding the machine user to your repository ⚓
- Create a new GitHub user account, one that will serve as the machine user.
- Go to your repository on GitHub and select the Settings tab.
On the left side menu, select Collaborators & teams.
- Scroll down to the Collaborators window.
- In the search input field, search for the username of your newly created account.
- Click Add Collaborator.
Change the user permission to Read.
By default, the invited collaborator’s permission is Write. You can keep it that way, of course, but a Read permission is enough for Bitrise.
Adding the SSH key to the machine user ⚓
In order for Bitrise to be able to use the machine user to access your repository, you must add the same SSH key to the machine user and the app on Bitrise.
When adding a new app:
- Start the process of adding your app on Bitrise.
When prompted to setup repository access, you can choose either Automatic or Add own SSH:
- If you choose Add own SSH, you can generate your own SSH keypair. Provide the generated SSH key for the app and add the public key to your GitHub machine user.
- If you choose Automatic, click I need to when asked if you need to use an additional private repository. Copy the SSH public key to your GitHub machine user.
- Finish the process.
If your app already exists:
- Open your app on Bitrise.
- Go to the Settings tab.
- Scroll down to SSH settings.
- Click the Click to show SSH public key button.
- Copy the SSH public key and add it to your GitHub machine user.
Git cloning submodules and repository dependencies ⚓
You have two options when it comes to accessing multiple repositories during a Bitrise build: you either clone all the repositories on the virtual machine, and access them as needed, or you add the additional repositories as submodules to your main repo. In the latter case, you do not need to worry about cloning them: if you set up SSH access correctly, the Git Clone Step will take care of everything.
If you don’t want to or can’t add your repository dependencies as submodules, read on: we’ll talk about how to clone them.
Note that the Git Clone Step only works with the main repository. If you need to access multiple private repositories, do not add multiple Git Clone Steps. Use Script Steps to clone those repositories on the Bitrise virtual machine.
To clone additional private repositories during the build:
- Make sure you added a user with the Bitrise public SSH key to all the repositories.
- Make sure you have the Activate SSH Key Step and the Git Clone Step at the start of your Workflow.
- Add one or more Script Steps to clone the additional private repositories to the build.
- Run a build.
And that’s it!
Creating SSH keys for a new private app ⚓
There are three options to grant Bitrise access to your repository:
- Auto-add SSH keypair: Don’t use this option if you use submodules. This option adds the SSH key to the main repository only.
- Generate SSH keypair: this generates a key for you on the Bitrise website and you will have to copy it manually to the given user. This is the recommended option if you want to use submodules or have to access multiple repositories during your build.
- Use your own SSH keypair: can be used if you also have the private key of the given user. You just have to paste the private key and Bitrise will be able to access the repositories. Keep in mind that the SSH key has to be an RSA key, without a passphrase! You can find an example of how you can generate a key like that here.
Managing SSH keys of an existing private app ⚓
You can find the public SSH key of the app in the
Settings of the given
app on Bitrise. Scroll down to the
SSH settings section
Show SSH Public Key.
Copy the key to the given user and you are ready to build!
If necessary, update the given app’s SSH key by clicking the
Change SSH Keypair button and choosing one of the three options.
This guide explains how to grant access for bitrise.io to your Bitbucket team, and to check if you denied access for any reason.
This guide explains how to grant access for bitrise.io to your GitHub Organization. This way Bitrise can access the Organization's repositories.
If you want to do manual SSH key configuration on bitrise.io, you can generate an appropriate SSH keypair with a simple Command Line / Terminal command.