Use deployment keys

You can use deployment keys with your Bitbucket Cloud 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 Cloud.

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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

15 Archived comments

  1. User avatar


    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?

    19 Feb 2014
    1. User avatar

      Marcus Bertrand [Atlassian]

      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.

      19 Feb 2014
      1. User avatar

        Kaz Nishimura

        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?

        21 Jan 2015
  2. User avatar

    Dirk Estievenart

    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

    01 Apr 2014
  3. User avatar

    willem dhaeseleer

    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


    10 Apr 2014
  4. User avatar

    Alexander Bondarenko

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

    No, you can't. Please fix.

    28 Jul 2014
  5. User avatar


    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?

    09 Oct 2014
  6. User avatar


    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. 
    09 Oct 2014
  7. User avatar

    John Simpson

    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?

    12 Nov 2014
    1. User avatar

      Dan Stevens [Atlassian]

      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,


      13 Nov 2014
      1. User avatar

        John Simpson

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

        Deployment keys don't.

        13 Nov 2014
        1. User avatar

          Dan Stevens [Atlassian]

          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,



          13 Nov 2014
          1. User avatar

            John Simpson

            That's exactly what I did.

            13 Nov 2014
  8. User avatar


    Hi there, I am not very experienced in using git for code deployment yet but require help in getting the following working:

    What is best method to "connect" a test system with a repo?

    1. Should I create a key pair locally and drop the secure key into the test system and add the pub key to the related repo? (insecure, as we use cloud-init for provisioning and the related meta data are quite easy to fetch =risk of exposing the secure key to most developers on that system)
    2. The server creates key pairs on build. Those keys are protected from access by any developer account.
      Should I "inject" the public key to the test repo? If so: how to get this automated? (any example?)
    3. Any other methods?

    Our test systems are re-built from scratch for, obviously, testing purposes.
    We are using cloud-config to provision & configure the servers quickly = 100% automation (no config mgmt required here = no puppet, no chef,...). I want to avoid ending up being enforced to login into each server manually to get the pub key and insert it to the related repo.



    08 Apr 2015
  9. User avatar

    Arvid Jakobsson

    I wrote a script for adding the same deploy key to several repositories at once:

    31 Jul 2015
Powered by Confluence and Scroll Viewport