Using GPG keys

Still need help?

The Atlassian Community is here for you.

Ask the community

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:

  1. In a terminal, use this command to list GPG keys you have access to:

    gpg --list-secret-keys --keyid-format LONG
  2. Check the output to see if you have a GPG key pair.

  3. 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:

  1. In a terminal, use this command to generate a GPG key:

    gpg --gen-key
  2.  Provide the information asked at the prompts.
    1. Enter your identifying information.
    2. Enter a secure passphrase.

  3. Use this command to list your GPG keys.

    gpg --list-secret-keys --keyid-format LONG
  4. Copy 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]

  5. Get your public key you'll add to Bitbucket Server.

    1. Paste the GPG key ID into this command to export the public key you will enter in Bitbucket Server.

      gpg --armor --export 7FFFC09ACAC05FD0

    2. From 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:

  1. From within Bitbucket Server, go to your account by clicking your profile picture in the upper-right, and select Manage account.

  2. Click GPG keys. > Add key.

  3. Copy your GPG key.

    Show me how to do this...

    From a terminal, use this command to copy your GPG key to your clipboard:

    gpg --armor --export MY_KEY_ID | pbcopy

  4. 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:

  1. Copy your GPG key ID.

    Show me how to do this...

    To list your GPG keys, use this command:

    gpg --list-secret-keys --keyid-format LONG


    Copy 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]

  2. 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:

To sign commits with your GPG key:

  1. When committing changes to a local branch, use the -S flag to the git commit command:

    git commit -S -m your commit message
  2. 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
Last modified on Jan 4, 2021

Was this helpful?

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