Can I add projects with submodules or with private repo dependencies?

If you have a project with one or more submodules or other private repository dependencies (for example, CocoaPods repositories), you have to grant access to all repositories for a successful build.

There are two ways to achieve this:

Use a machine user with read only access

It is not required to use a special bot/machine user: you can add the SSH key to your own account on the git hosting service. The best practice, however, is to use a machine user, with read only access, for those repositories you want to access during the build.

GitHub itself recommends this method for accessing multiple repositories.

On GitLab and Bitbucket it’s possible to register a single SSH key as a “Deployment key” to multiple repositories, without the need to create a “bot” / “machine” user.

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

  1. Create a new GitHub user account, one that will serve as the machine user.
  2. Go to your repository on GitHub and select the Settings tab.
  3. On the left side menu, select Collaborators & teams.

  4. Scroll down to the Collaborators window.
  5. In the search input field, search for the username of your newly created account.
  6. Click Add Collaborator.
  7. 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:

  1. Start the process of adding your app on Bitrise.
  2. When prompted to setup repository access, you can choose either Automatic or Add own SSH:

  3. Finish the process.

If your app already exists:

  1. Open your app on Bitrise.
  2. Go to the Settings tab.
  3. Scroll down to SSH settings.
  4. Click the Click to show SSH public key button.
  5. Copy the SSH public key and add it to your GitHub machine user.

Git cloning submodules and repository dependencies

There is one important detail to keep in mind when you want to give access to all submodules or private repository dependencies for an app: the app’s privacy settings determine what git URL should you use.

Cloning issues

If you encounter issues with git cloning - for example, not all submodules are cloned - try the following command after cloning:

git submodule update --recursive --remote --merge --force

Creating SSH keys for a new private app

There are three options to grant Bitrise access to your repository:

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 and click 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.