SSH access keys for system use

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Bitbucket Data Center and Server administrators can set up SSH access keys to secure the Git operations that other systems perform on the repositories managed in Bitbucket. Using access keys avoids the need to store user credentials on another system, and means that the other system doesn't have to use a specific user account in Bitbucket.  For example, access keys can be used to allow your build and deploy server  to authenticate with Bitbucket to check out and test source code.

  • Project admins can add and manage SSH access keys for a project. These keys apply to every repository in the project. And repository admins can add and manage SSH access keys for a particular repository. 
    Starting from Bitbucket 8.8, project admins can also restrict repository admins from managing repository-level access keys using the Restrict changes to repository settings dropdown. Note that when project admins restrict changes, any existing repository-level access keys added by the repository admins are not deleted automatically.
  • The access key can allow either read-only or read-write Git operations.
  • Because they are designed to be used for system access, SSH access keys may push commits that are not signed with a GPG key even if the "Verify Commit Signature" hook is enabled.


Bitbucket supports the following SSH key types:
  • ED25519
  • RSA2 (we recommend you use a key size of at least 2048 bits)
  • ECDSA
  • DSA (we recommend you use other key types)

Although Bitbucket supports the above key types, your admin can restrict specific key types and mandate minimum key lengths to make sure you’re using secure SSH keys. Learn more about how your admin can manage settings for SSH keys

Before you can use SSH keys to secure a connection with Bitbucket the following must have already been done: 

  • Your Bitbucket administrator must have already enabled SSH access, on Bitbucket.
  • Your Bitbucket administrator must already have enabled the option SSH access keys enabled on Bitbucket.
  • You must have already created an SSL key. See Creating SSH keys. Alternatively, you can use an existing key, if it isn't already being used for a personal account in Bitbucket.

Using SSH keys to allow access to Bitbucket repositories

To get the SSH key to work with your build, or other, system, you need to:

  • Add the private key to that system. For Bamboo, see this page: Shared credentials.
  • Add the public key to Bitbucket as described below.

Add an SSH access key to either a Bitbucket project or repository

You simply copy the public key, from the system for which you want to allow access, and paste it into Bitbucket.

  1. Copy the public key. One approach is to display the key on-screen using cat, and copy it from there:

    cat < ~/.ssh/id_ed25519.pub
  2. Now, in Bitbucket, go to the Settings tab for the project or repository.

  3. Click Access keys and then Add key.

  4. Paste the key into the text box.
  5. (Optional) Name your key to identify it easily.
  6. Choose the Read permission, for git pull or git clone operations for example, where you want to be sure that the system will not be able to write back to the Bitbucket repository.
    Choose the Read / Write permission, for git push or git merge operations for example, where you may want your build system to merge successful feature branch builds to the default branch in the Bitbucket repository, or so that deployments can be tagged. 
    Note that if you attempt to add a key already present on a project or repository but with a different permission to what it currently has, the permission and label will simply be updated.
  7. (Optional) Set an expiry so your key expires automatically.
    If your admin has set automatic expiry for all keys across Bitbucket, the key expires based on the limits they've set. If required, you can set the key to expire earlier than the limit they've set.
    Note that you can't edit the expiry after you create the key. 
  8. Click Add key.  

Bitbucket license implications

  • System access keys do not require an additional Bitbucket user license.

Reusing access keys

  • You can use the same SSH access key for multiple repositories or projects.
  • Keys used for personal user accounts can't be re-used as a project or repository system access key, and keys used as a project or repository access key can't be re-used for user accounts.

Deleting an access key

To delete an access key:

  1. Navigate to Repository Settings or Project SettingsAccess keys.
  2. Select More actions …. > Delete.

If the key is used for multiple projects or repositories, you can select the other places that you want the key to be deleted from: 

Note that the dialog only displays the projects and repositories that you have permission to see. Be aware that the key may also be used in other places that are not listed in the dialog. To be 100% sure that  all  uses of the key are deleted, this operation must be performed by someone with the administrator or sysadmin global permission .

Last modified on May 31, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.