Sign commits and tags with X.509 certificates
Verification of a signed commit or tag
For a signed commit or tag to be considered verified in Bitbucket Data Center, the following conditions should be met:
The signed Git content hasn’t been modified by a malicious third party and can be processed successfully.
There is a matching user known in Bitbucket Data Center that has the same email address as the one defined on the X.509 certificate used for signing.
Note that if there is more than one email address listed on the X.509 certificate, only the first email address will be used for matching to the user in Bitbucket Data Center.
The X.509 certificate has never been revoked.
Bitbucket Data Center will use the CRL (Certificate Revocation List) information of an issuing X.509 certificate to determine whether the signing X.509 certificate has been revoked or not.
CRL entries are fetched every 24 hours for freshness from a specified CRL distribution point from the issuing X.509 certificate. But if a manual update of the CRL entries is warranted, the fetching of CRL entries can be performed through the REST API for the given issuing X.509 certificate.
The X.509 certificate meets the defined validity period.
For any other case, the signature will be determined as not verified.
Installing smimesign
For the instructions to install smimesign, check the official GitHub documentation: smimesign (S/MIME Sign).
Configuring Git
You should configure Git globally or locally before using X.509 certificates to sign and verify commits and to sign tags.
Specify your X.509 key
If you're using an X.509 key that matches your committer identity, you can begin signing commits and tags without any further configuration.
However, if you aren’t using an X.509 certificate that matches your committer identity, you can list all your X.509 certificates that can be used by running the following command:
smimesign --list-keysFrom the list of X.509 keys, copy the ID value of the X.509 key that you'd like to use. For example, from the following sample output, the used ID is 4df4ce209319b0904fb3f2813115d5e4438e8c3c.
ID: 4df4ce209319b0904fb3f2813115d5e4438e8c3c
S/N: 468e1711b4ade3fc
Algorithm: SHA256-RSA
Validity: 2023-10-08 23:35:00 +0000 UTC - 2024-10-08 23:35:00 +0000 UTC
Issuer: CN=DigiCert SHA2 Assured ID CA,OU=www.digicert.com,O=DigiCert Inc,C=US
Subject: CN=Bitbucket,OU=Enterprise,O=Atlassian,L=Sydney,ST=NSW,C=AU
Emails: bitbucket@example.comGlobal configuration
If you’d like to configure the global signing of your commits and tags with X.509 keys for all repositories, use the following commands:
git config --global gpg.x509.program smimesign
git config --global gpg.format x509
git config --global user.signingkey <ID>The <ID> in the last command corresponds to the ID of your X.509 key. In the example, the value for <ID> is 4df4ce209319b0904fb3f2813115d5e4438e8c3c.
Local configuration
If you’d like to configure signing your commits and tags with X.509 keys locally for a single repository then navigate to that repository you would like to use and use the following commands:
git config --local gpg.x509.program smimesign
git config --local gpg.format x509
git config --local user.signingkey <ID>The <ID> in the last command corresponds to the ID of your X.509 key. In the example, the value for <ID> is 4df4ce209319b0904fb3f2813115d5e4438e8c3c.
Signing and verifying commits with X.509 certificates
Once your Git configuration has been set up with an X.509 certificate, you can begin signing your commits and tags and verifying the signed commits and tags locally.
Sign commits
To sign commits, run the following command:
git commit -S -m "Signed with an X.509 certificate"Verify commits locally
To verify commits locally, run the following command:
git log --show-signatureAfter running the command, you should see a message similar to the following:
commit 29463c73b2bf9d9be670b24c5c64d213117cb748
smimesign: Signature made using certificate ID 0x298d2e3a40096cdf3c8855c7f1a85dbc08c59ab6
...The certificate ID from the Git command should match both of the following SHA-1s:
the SHA-1 in the Bitbucket Data Center verification dialog for the verified commit
the SHA-1 of the signing X.509 certificate
Sign tags
To sign tags, run the following command:
git tag -s v1.0.0 -m "Tag signed with an X.509 certificate"