Enabling SSH access to Git repositories in Bitbucket Server
A Bitbucket Server administrator can enable SSH access to Git repositories in Bitbucket Server. This allows your Bitbucket Server users to:
- add their own SSH keys to Bitbucket Server
- use those SSH keys to secure Git operations between their computer and the Bitbucket Server instance.
Bitbucket Server users must each add their own SSH key pairs to their Bitbucket Server account to be able to use SSH access to repositories.
Supported key types are DSA, RSA2, and Ed25519. Note that RSA1 is not supported. We've tested key sizes of 768, 1024, 2048, 4096 and 8192 bytes.
On this page:
Related pages:
Performance
There are performance implications for Bitbucket Server when using SSH. When users connect to Bitbucket Server 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 Server bundles a version of the Apache Mina SSHD server. Bitbucket Server's SSH server is not integrated with the SSH server on the host Bitbucket Server is running on nor does it consider the users on the host when authenticating Bitbucket Server users. To prevent security issues, the embedded SSH server has been locked down to allow the 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 Server, 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:
- Go to the Bitbucket Server administration area and click Server settings (under 'Settings').
- Under 'SSH access', check SSH enabled.
- Enter values for SSH port and SSH base URL, according to the information in the sections below.
- Click 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 Server.
This is the base URL that Bitbucket Server 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 Server base URL, with the port that SSH is listening on. See Specifying the base URL for Bitbucket Server.
For example, if the SSH base URL is not set and the Bitbucket Server 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 Server. 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 Server.
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.
| Port forwarding | SSH base URL | Bitbucket Server base URL | SSH port | Resulting SSH URL for a repo |
|---|---|---|---|---|
 | Not set | | 7999 | ssh://git@bitbucket.atlassian.com:7999/<projectname>/<reponame>.git |
22 –> 7999 | | | 7999 | ssh://git@bitbucket.atlassian.com/<projectname>/<reponame>.git |
PortWhen running Bitbucket Server behind a proxy
If you run Bitbucket Server 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 Server is actually running on (and the URL should include the SSH port Bitbucket Server 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 Server. 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 Server.
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
| Port forwarding | SSH base URL | SSH port | Bitbucket Server base URL | Resulting SSH URL for a repo |
|---|---|---|---|---|
| ssh://bitbucket.backend.atlassian.com:7999 | 7999 | | ssh://git@bitbucket.backend.atlassian.com:7999/<projectname>/<reponame>.git |
22–>7999 | | 7999 | | ssh://git@bitbucket.atlassian.com/<projectname>/<reponame>.git |
44–>7999 | | 7999 | | ssh://git@bitbucket.atlassian.com:44/<projectname>/<reponame>.git |