SSH access keys for system use

Stash administrators can set up SSH access keys to secure the Git operations that other systems perform on the repositories managed in Stash. 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 Stash. For example, access keys can be used to allow your build and deploy server to authenticate with Stash to check out and test source code.

  • Project admins can add and manage SSH access keys for a project. The keys apply to every repository in the project.
  • Repository admins can add and manage SSH access keys for a particular repository.
  • The access key can allow either read-only or read-write Git operations.

Note that Stash supports DSA and RSA2 key types – RSA1 is not supported.

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

  • Your Stash administrator must have already enabled SSH access, on Stash.
  • 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 Stash.

Using SSH keys to allow access to Stash 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 Stash as described here:

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

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

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

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

  3. Click Access keys and then Add key.

  4. 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 Stash 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 Stash 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 will simply be updated.
  5. Paste the key into the text box and click Add key.

     

Stash license implications

  • System access keys do not require an additional Stash 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

You can delete an access key by going to SettingsAccess keys for the repository, and clicking the cross for the key (the cross only appears when you move the mouse pointer there):

 

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.

Redirection notice

This page will redirect to /display/BitbucketServer/SSH+access+keys+for+system+use .

Stash administrators can set up SSH access keys to secure the Git operations that other systems perform on the repositories managed in Stash. 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 Stash. For example, access keys can be used to allow your build and deploy server to authenticate with Stash to check out and test source code.

  • Project admins can add and manage SSH access keys for a project. The keys apply to every repository in the project.
  • Repository admins can add and manage SSH access keys for a particular repository.
  • The access key can allow either read-only or read-write Git operations.

Note that Stash supports DSA and RSA2 key types – RSA1 is not supported.

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

  • Your Stash administrator must have already enabled SSH access, on Stash.
  • 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 Stash.

Using SSH keys to allow access to Stash 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 Stash as described here:

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

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

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

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

  3. Click Access keys and then Add key.

  4. 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 Stash 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 Stash 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 will simply be updated.
  5. Paste the key into the text box and click Add key.

     

Stash license implications

  • System access keys do not require an additional Stash 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

You can delete an access key by going to SettingsAccess keys for the repository, and clicking the cross for the key (the cross only appears when you move the mouse pointer there):

 

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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport