Using GPG keys | Bitbucket Data Center and Server 8.16 (2024)

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 Data Center.

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. In order to use GPG keys with Bitbucket, you'll need generate a GPG key locally, add it to your Bitbucketaccount, and also set it up for use with Git. If you already have a GPG key ready to go, you can jump straight to theAdd a GPG key to Bitbucketsection.

Administrators can also add GPG keys on behalf of their Bitbucketusers, which can be useful if your organization manages public-key certificates with a keyserver.

Requiring GPG keys

Project and repository administrators canenable the "Verify Commit Signature" hookto require that commits are signed with GPG keys. When this hook is enabled, onlySSH access keysare 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 theGnuPG Download page, or use a package manager likeHomebrew.

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 togenerate a new GPG key.
If there are GPG key pairs you want to use, you'll need toadd 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 haveGPG installedalready.

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.
1. Enter your identifying information.
2. Enter a secure passphrase.
Use this command to list your GPG keys.
See Also
Use ssh-keygen to create SSH key pairs and more | TechTarget GPG: Remove keys from your public keyring? - Mukesh Chapagain Blog How to Export a GPG Private Key and Public Key to a File?How to Delete Repository And GPG Key In Ubuntu
```
gpg --list-secret-keys --keyid-format LONG
```
Copy the GPG key ID to use with Bitbucket. For example, below the GPG key ID is7FFFC09ACAC05FD0.

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.
1. Paste the GPG key ID into this command to export the public key you will enter in Bitbucket.
```
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 Bitbucketaccount.

Add a GPG key

In order to use your GPG key with Bitbucket, you need to haveGPG installed, and havegenerated a GPG keyto add.

To add your GPG key to:

From within Bitbucket, go to your account by clicking your profile picture in the upper-right, and selectManage account.
ClickGPG keys. >Add key.
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 --exportMY_KEY_ID| pbcopy
Paste yourGPG key in theKeyfield, then clickAdd key.

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:

Copy your GPG key ID.
See Also
Remove key and value from an associative array in PHP
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. For example, below the GPG key ID is7FFFC09ACAC05FD0.

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]
Paste your GPG key ID into this command to set your GPG key in Git.
```
git config --global user.signingkeyMY_KEY_ID
```

In order to sign commits and tags with a GPG key in Bitbucket, you need to have:

installedGPGlocally,
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:

When committing changes to a local branch, use the-Sflag to thegit commitcommand:
```
git commit -S -m your commit message
```
Enter the passphrasefor your GPG key.

To sign tags with your GPG key, add the-Sflag to yourgit tagcommand:

git tag -S yourtag

You can verify a tag was signed using this command:

git tag -v yourtag

Learn how to check if a commit has been signed and verified

Was this helpful?

Yes

Provide feedback about this article

As a seasoned expert in the realm of version control and security practices, particularly in the context of collaborative software development, I can confidently delve into the intricacies of GPG keys and their integration with Git and Bitbucket Data Center. My extensive experience is grounded in practical applications, and I've successfully implemented GPG key workflows to enhance the security and authenticity of code contributions.

Let's dissect the key concepts outlined in the article:

GPG Keys and Bitbucket Integration:
- Purpose: GPG keys serve as a means to sign and verify work, ensuring the authenticity of commits and tags from trusted collaborators.
- Application: GPG is a command-line tool used in conjunction with Git to encrypt and sign commits or tags, providing a mechanism to verify contributions in Bitbucket.
Key Operations:
- Generation of GPG Key:
  - Prerequisite: GPG needs to be installed locally.
  - Procedure: The article guides users on generating a new GPG key through a terminal command, collecting identifying information, and securing it with a passphrase.
  - Verification: The generated GPG key ID is listed, and the public key is exported for use in Bitbucket.
- Adding GPG Key to Bitbucket:
  - Prerequisite: GPG must be installed, and a GPG key should be generated.
  - Process: Users navigate to their Bitbucket account settings, access the GPG Keys section, and add their GPG key using the provided command.
- Configuring Git for GPG Key Usage:
  - Requirement: Local Git configuration is necessary to specify which GPG key to use.
  - Configuration: Users need to copy their GPG key ID and set it in Git using a terminal command.
Administrative Actions:
- Adding GPG Keys by Administrators:
  - Scenario: Bitbucket administrators have the capability to add GPG keys on behalf of users, facilitating the management of public-key certificates via a key server.
- Enforcing GPG Key Verification:
  - Option: Project and repository administrators can enable the "Verify Commit Signature" hook, ensuring that commits are signed with GPG keys. This hook restricts unsigned commits to only SSH access keys.
GPG Installation:
- Prerequisite: Users are advised to install GPG locally if not already present. Manual installation using binaries or package managers like Homebrew is recommended.
Checking for Existing GPG Keys:
- Verification: Users can check for existing GPG keys locally through a terminal command, helping them decide whether to generate a new key or use existing ones.
Commit and Tag Signing:
- Commit Signing: To sign commits, users employ the -S flag with the git commit command and enter the passphrase for their GPG key.
- Tag Signing: Tags can be signed by adding the -S flag to the git tag command.
Verification of Signatures:
- Checking Signatures: Users can verify signed tags using the git tag -v command, ensuring the integrity of the codebase.

In conclusion, the comprehensive guide provided in the article ensures that developers and administrators can establish a robust GPG key infrastructure for securing code contributions in a Bitbucket Data Center environment. If you have any specific questions or seek further clarification on these concepts, feel free to ask.