Managing multiple Project Access keys on one device

If you have a tool or script that requires access to more than one Bitbucket Cloud projects through SSH, some additional configuration is required to ensure that Git connects to Bitbucket with the correct SSH key for each repository cloned to your device.

To configure your device to access repositories across multiple project using read-only Project Access Keys:

  1. Check that SSH is installed (see the relevant SSH setup guide for your operating system).

  2. Create an SSH key pair for each project in the ~/.ssh/ directory, such as:

    1 2 cd ~/.ssh/ ssh-keygen -t ed25519 -b 4096 -C "{}" -f {ssh-key-name}
  3. Add the public keys to the corresponding projects on Bitbucket Cloud (see the relevant SSH setup guide for your operating system).

  4. Create or update a .gitconfig for each Bitbucket project (not the user’s global Git configuration at ~/.gitconfig) and include the core.sshCommand setting, with an ssh command that uses the private key for the project, such as:

    1 2 [core] sshCommand = ssh -i ~/.ssh/project1_private_ssh-key-name


    1 2 [core] sshCommand = ssh -i ~/.ssh/project2_private_ssh-key-name
  5. Update the user’s global Git configuration file ~/.gitconfig to conditionally include the project Git configuration file using the includeIf setting. For example:

    1 2 3 4 5 [includeIf "gitdir:~/project1/"] path = ~/project1/.gitconfig [includeIf "gitdir:~/project2/"] path = ~/project2/.gitconfig

    This would allow all repositories cloned into the project folder (such as ~/project1/repo1) to use the same Git configuration and Access Key (such as ~/project1/.gitconfig).

Additional Help