Using GPG keys
GPG keys are a way to sign and verify work from trusted collaborators. This page describes how to generate a GPG key to sign and verify commits and tags for use with Bitbucket Server.
On this page:
About GPG keys
GPG is a command line tool used together with Git to encrypt and sign commits or tags to verify contributions in Bitbucket Server. In order to use GPG keys with Bitbucket Server, you'll need generate a GPG key locally, add it to your Bitbucket Server account, and also set it up for use with Git. If you already have a GPG key ready to go, you can jump straight to the Add a GPG key to Bitbucket Server section.
Administrators can also add GPG keys on behalf of their Bitbucket Server users, which can be useful if your organization manages public-key certificates with a keyserver.
Requiring GPG keys
Project and repository administrators can enable the "Verify Commit Signature" hook to require that commits are signed with GPG keys. When this hook is enabled, only SSH access keys are allowed to push unsigned commits.
Install GPG
If you don't already have GPG, you'll need to install it locally. You can install GPG manually using binaries for your operating system on the GnuPG Download page, or use a package manager like Homebrew.
Check for existing GPG keys
If you're not sure if you have a GPG key already, you can check for existing GPG keys locally.
To check if you have existing GPG keys:
In a terminal, use this command to list GPG keys you have access to:
gpg --list-secret-keys --keyid-format LONG- Check the output to see if you have a GPG key pair.
- If there are no GPG key pairs, you'll need to generate a new GPG key.
If there are GPG key pairs you want to use, you'll need to add them to your Bitbucket Server account.
Generate a new GPG key
In order to generate a new GPG to sign commits and tags you need to have GPG installed already.
To generate a new GPG key:
In a terminal, use this command to generate a GPG key:
gpg --gen-key- Provide the information asked at the prompts.
- Enter your identifying information.
- Enter a secure passphrase.
Use this command to list your GPG keys.
gpg --list-secret-keys --keyid-format LONGCopy the GPG key ID to use with Bitbucket Server. For example, below the GPG key ID is
7FFFC09ACAC05FD0.gpg --list-secret-keys --keyid-format LONG
/Users/bitbucketbot/.gnupg/pubring.gpg
------------------------------
sec rsa2048/7FFFC09ACAC05FD0 2017-06-02 [SC] [expires: 2019-06-02]
5538B0F643277336BA7F0E457FFFC09ACAC05FD0
uid [ultimate] BitbucketBot <bitbucket@realaddress.com>
ssb rsa2048/95E8A289DFE77A84 2017-06-02 [E] [expires: 2019-06-02]Get your public key you'll add to Bitbucket Server.
Paste the GPG key ID into this command to export the public key you will enter in Bitbucket Server.
gpg --armor --export 7FFFC09ACAC05FD0From the output, copy your public GPG key, which starts at
-----BEGIN PGP PUBLIC KEY BLOCK-----
and ends at-----END PGP PUBLIC KEY BLOCK-----.
You can now add your public GPG key to your Bitbucket Server account.
Add a GPG key to Bitbucket Server
In order to use your GPG key with Bitbucket Server, you need to have GPG installed, and have generated a GPG key to add.
To add your GPG key to Bitbucket Server:
- From within Bitbucket Server, go to your account by clicking your profile picture in the upper-right, and select Manage account.
- Click GPG keys. > Add key.
Copy your GPG key.
- Paste your GPG key in the Key field, then click Add key.
Configure Git to use your GPG key
In order to use GPG keys with Bitbucket Server, you need to configure your local version of Git which GPG key to use.
To configure Git to use your GPG key:
Copy your GPG key ID.
Paste your GPG key ID into this command to set your GPG key in Git.
git config --global user.signingkey MY_KEY_ID
Sign commits and tags with a GPG key
In order to sign commits and tags with a GPG key in Bitbucket Server, you need to have:
- installed GPG locally,
- added a GPG key to your Bitbucket Server account, and
- configured your local version of Git which GPG key to use.
To sign commits with your GPG key:
When committing changes to a local branch, use the
-Sflag to thegit commitcommand:git commit -S -m your commit message- Enter the passphrase for your GPG key.
To sign tags with your GPG key, add the -S flag to your git tag command:
git tag -S yourtag
You can verify a tag was signed using this command:
git tag -v yourtag