Skip to end of metadata
Go to start of metadata

You can use deployment keys with your Bitbucket repositories. A deployment key grants read-only access to a public or private repository. With a deployment key a user or a process can pull or clone a repository over SSH. Deployment keys have the following features and limitations:

  • Deployment keys do not apply to your plan limit. 
  • You can add the same deployment key to multiple repositories.
  • The deployment key must be unique — it cannot also be associated with an account.

Deployment keys are useful for authenticating a build server to checkout and test your code.   

Before you begin

Make sure you have already generated your deployment key. For detailed information on the SSH protocol and generating keys, see Use the SSH protocol with Bitbucket.

How to add a deployment key

If you are using the deployment key for building code, make sure your build server has the key installed. For example, if you are using Bamboo to build your code, make sure each agent has the key installed. To add a deployment key to Bitbucket, do the following:

  1. Log into a repository under an account with administrative rights.
  2. Go to the repository's settings .
  3. Click Deployment keys from the left hand menu.
  4. Press Add Key.
    The system displays the Add SSH Key dialog.
  5. Enter a label and the key.
  6. Press Add key.
    Bitbucket notifies you via email that a key was added to your account.

If you are using your key for a build system, it is a good idea to confirm the key is working correctly from the build server (or Bamboo agent). For example, you could manually clone a repository on the server using the SSH protocol and the key.   If you have trouble using your key, see Troubleshoot SSH Issues.

Edit a deployment key

After you add a key, you can edit the key's Label but not the key itself. If you need to change the key's contents, you must delete and re-add the key.  This is a security measure. In the event your account security was hacked without your knowledge, the hacker could not replace or damage your existing keys.




  1. Anonymous

    We am using Jenkins as a build server and the builds are working as expected (connecting and cloning the repo's). We are having an issue with TAGGING the build, I know this is because the Deployment Keys have read only access but can we let our build servers TAG the builds?

    1. Sorry, as this would require write access to the repository, this won't be possible. If you need to tag your builds, we recommend setting up a full SSH key on your team/account.

      1. I just would like to grant write access on a specific repository to an automatic build server. Is it permitted for a user to have such an extra account?

  2. Using Jenkins here too. (smile)

    But the problem is that we change the keys regularly (part of security policy).

    We find it quite cumbersome to add the deployment key to each of our projects. It would be much easier if we could manage the deployment keys and in an easy way assign the key to multiple projects (or the other way around: assign multiple projects to the same key). Is there a way to do so?

    We found a way to do this by adding the key at the team level, but we don't know which rights we have doing so. We'd really need it to be read-only (as a deployment key).

    BTW, the "Get Answers" link below is still linked to the Google group and not to

  3. Dirk Estievenart, I'm pretty sure you could use the api to update all keys in a more integrated way. check out the documentation:

     deploy-keys Resourcessh-keys Resource


    • You can add the same deployment key to multiple repositories.

    No, you can't. Please fix.

  4. Alexander Bondarenko We do have multiple repositories each sharing multiple deployment keys - are you sure you are not trying to add a key which is tied to an existing user or so?

  5. Hello. I have a problem with deployment keys for repo "homo-tour" ( . I added new deployment key with label "activeby-server" ( When I try to clone repo from bitbucket I get an error:

    -bash-3.2$ git clone
    Initialized empty Git repository in /home/p.mikhnevi.d96d6/www/homo-tour/.git/
    Host key verification failed.
    fatal: The remote end hung up unexpectedly
    Help me please. 
  6. Our account has over 300 repos associated with it. I've just added an SSH key to the account, so all of the jobs on our build servers are able to clone the code (which is good, no more having to manually add the key to every single repo) however all of those jobs now have access to commit back into the repo as well (which is not so good.)

    Is there a way to create an account-level SSH key with read-only access?

    1. Hey John,
      Thanks for taking the time to comment.

      You can try the following:

      • create a Bitbucket account
      • add it to your team
      • give it read only access to the team's repositories
      • assign the SSH key to the new account.
      • use it for your build servers.

      Hope this helps.

      Happy coding,


      1. Our account has a fixed number of users, and doing this would use one of our user slots.

        Deployment keys don't.

        1. Oh, of course, apologies.

          So I see you've added the key at the account level, does that mean a user account or did you add it to your team? The only other solution I can think of is adding the key to your team by doing the following:

          1. Log in as a team administrator.
          2. Select Team>your-teamname.
          3. Click Manage team.
          4. Click SSH keys
          5. Click  Add key.

          But I believe you've already done that if I understand you correctly. I would suggest contacting support using the button on this page.

          Sorry I don't have a better answer for you.

          Happy coding,



          1. That's exactly what I did.