Use GPG keys to sign commits

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 or tags for use with Bitbucket Cloud.

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. In order to use GPG keys with Bitbucket, you'll need generate a GPG key locally, add it to your Bitbucket 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 section. 

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, such as Homebrew.

To install the GPG command line tools using 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:

   1 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 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:

   1 gpg --full-generate-key

2.  Provide the information asked at the prompts.

   1. Enter your identifying information.

   2. Enter a secure passphrase.

1. Use this command to list your GPG keys.

   1 gpg --list-secret-keys --keyid-format=long

2. Copy the GPG key fingerprint to use with Bitbucket. For example, below the GPG key fingerprint is 8F2F8C1E26E0069BC7FE7E258AEDA33EA0CA3AF6.

   1 2 3 4 5 6 7 8 9 10 11 12 gpg --list-secret-keys --keyid-format=long gpg: checking the trustdb gpg: marginals needed: 3 completes needed: 1 trust model: pgp gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u gpg: next trustdb check due at 2025-10-24 [keyboxd] --------- sec ed25519/8AEDA33EA0CA3AF6 2024-10-24 [SC] [expires: 2025-10-24] 8F2F8C1E26E0069BC7FE7E258AEDA33EA0CA3AF6 uid [ultimate] eilen shahbaz (my bitbucket gpg key) <eshahbaz@atlassian.com> ssb cv25519/5123BDCC83E0FF13 2024-10-24 [E] [expires: 2025-10-24]

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

   1 2 gpg --armor --export 8F2F8C1E26E0069BC7FE7E258AEDA33EA0CA3AF6 # Prints the GPG key ID, in ASCII armor format

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

Add a GPG key

In order to use your GPG key with Bitbucket, you need to have GPG installed, and have generated a GPG key to add.

To add your GPG key to:

1. Select Settings ⚙️ on the top navigation bar.

2. Select Personal Bitbucket settings from the Settings dropdown menu.

3. Select GPG keys under Security on the left sidebar.

4. Select the Add key button.

5. (Optional) Provide a name for your GPG key.

6. Copy your GPG key.

7. Paste your GPG key in the Key field.

8. Select the Add key button.

Configure Git to use your GPG key

In order to use GPG keys with Bitbucket, 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.

   • To list your GPG keys, use this command:

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

    

   Copy the GPG key ID to use with Bitbucket. For example, below the GPG key ID is 7FFFC09ACAC05FD0.

   1 2 3 4 5 6 7 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.

   1 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, you need to have:

• installed GPG locally,

• added a GPG key to your Bitbucket account, and 

• configured your local version of Git which GPG key to use.

To sign commits with your GPG key:

1. Tell git about your key using fingerprint or key_id, for example, 8F2F8C1E26E0069BC7FE7E258AEDA33EA0CA3AF6

   1 git config --global user.signingkey <KEY_ID>

2. Run the following command in the zsh shell to add the GPG key to your .zshrc file, if it exists, or your .zprofile file:

   1 2 3 if [ -r ~/.zshrc ]; then echo -e '\nexport GPG_TTY=$(tty)' >> ~/.zshrc; \ else echo -e '\nexport GPG_TTY=$(tty)' >> ~/.zprofile; fi source ~/.zshrc && source ~/.zprofile

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

   1 git commit -S -m "your commit message"

4. Enter the passphrase for your GPG key.

5. Verify that your commit was signed

   1 git log --show-signature

Signature verification statuses