Enable SSH access to Git repositories

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Administrators can enable SSH access to Git repositories in Bitbucket Data Center and Server. This allows users to:

  • add their own SSH keys to Bitbucket
  • use those SSH keys to secure Git operations between their computer and the Bitbucket instance.

Each user must add their own SSH key pairs to their account to be able to use SSH to access repositories.

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)

Performance

Using SSH has performance implications. When users connect to Bitbucket using SSH the encryption of data adds to overall CPU usage. See Scaling Bitbucket Server for more information.

Security

To implement SSH authentication support, Bitbucket bundles a version of the Apache Mina SSHD server. The Bitbucket SSH server is not integrated with the SSH server on the host Bitbucket is running on, and it doesn't consider the users on the host when authenticating Bitbucket users.

To prevent security issues, the embedded SSH server has been locked down to allow execution of a small set of commands for Git hosting. The only commands that are supported are git upload-pack, git receive-pack, git archive-pack and whoami (a custom whoami implemented in Bitbucket, not the whoami command that exists on Linux). It is not possible to open an SSH shell using the embedded server to execute arbitrary commands on the server.

Enabling SSH access

To enable SSH access:

  1. Go to  > Server settings.
  2. Select SSH enabled.
  3. Enter values for SSH port and SSH base URL, according to the information in the sections below.
  4. Select Save


These options will only be available if the "Bitbucket Server - SSH" app is enabled. For instructions on how to enable this app on your instance, please refer to Disabling and enabling apps.

For Data Center installations, a load balancer setup is required for SSH. For instructions on how to install and configure your load balancer, refer to Install Bitbucket Data Center.


SSH base URL 

The SSH base URL is the base URL with which users can access the SSH push/pull/clone functionality of Bitbucket.

This is the base URL that Bitbucket will use when displaying SSH URLs to users. If you do not set this, it will default to the host that is set in Bitbucket base URL, with the port that SSH is listening on. See Specify the Bitbucket base URL.

For example, if the SSH base URL is not set and the Bitbucket base URL is https://bitbucket.atlassian.com and the SSH port is 7999, the SSH URL for the repository Jira in the project Atlassian will be ssh://git@bitbucket.atlassian.com:7999/ATLASSIAN/jira.git

If you set up port forwarding, you will need to set the SSH base URL to the machine and port that is being forwarded to Bitbucket. However, you do not need to specify the port portion of the URL if the default SSH port (port 22) is being forwarded to Bitbucket.

If the SSH base URL and SSH port configurations are modified in the global Server settings page, the configurations specified in the properties file will no longer be used. 


Bitbucket_SSH_direct


Port forwardingSSH base URL

Bitbucket base URL

SSH portResulting SSH URL for a repo
(error)Not sethttps://bitbucket.atlassian.com 7999ssh://git@bitbucket.atlassian.com:7999/<projectname>/<reponame>.git

(tick) Port

22 –> 7999

https://bitbucket.atlassian.com https://bitbucket.atlassian.com 7999ssh://git@bitbucket.atlassian.com/<projectname>/<reponame>.git


When running Bitbucket behind a proxy

If you run Bitbucket behind a http proxy such as Apache (e.g. as per our instructions), and if Apache runs on a different host, SSH will not be available on that host. Instead, you will need to set the SSH base URL to the machine Bitbucket is actually running on (and the URL should include the SSH port Bitbucket is serving from).

For example, if the SSH base URL is set to ssh://bitbucket.backend.atlassian.com:7999, the SSH URL for the repository Jira in the project Atlassian will be ssh://git@bitbucket.backend.atlassian.com:7999/ATLASSIAN/jira.git

If you set up port forwarding, you will need to set the SSH base URL to the proxy machine and port that is being forwarded to Bitbucket However, you do not need to specify the port portion of the URL if the default SSH port (port 22) is being forwarded to Bitbucket.

For example, if you set up port forwarding from your http proxy host, bitbucket.atlassian.com, port 22, to bitbucket.backend.atlassian.com port 7999, set the SSH base URL to ssh://bitbucket.atlassian.com. Then, the SSH URL for the repository Jira in the project Atlassian will be ssh://git@bitbucket.atlassian.com/ATLASSIAN/jira.git



Bitbucket_SSH_URL



Port forwardingSSH base URLSSH port

Bitbucket base URL

Resulting SSH URL for a repo
(error)ssh://bitbucket.backend.atlassian.com:79997999https://bitbucket.backend.atlassian.com ssh://git@bitbucket.backend.atlassian.com:7999/<projectname>/<reponame>.git

(tick) Port

22–>7999

ssh://bitbucket.atlassian.com
7999https://bitbucket.backend.atlassian.com ssh://git@bitbucket.atlassian.com/<projectname>/<reponame>.git

(tick) Port

44–>7999

ssh://bitbucket.atlassian.com:44
7999https://bitbucket.backend.atlassian.com
ssh://git@bitbucket.atlassian.com:44/<projectname>/<reponame>.git
Last modified on Nov 15, 2022

Was this helpful?

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