Signed system commits
Enable signed system commits
System commit signing is disabled by default. You need to be a system administrator to configure signed system commits.
To turn on signed system commits:
Go to Global administration > Signed system commits.
Select On.
Select Save.
Here’s how the information on a signed system commit is displayed in the user interface.
Download the system GPG key
You can use the system public GPG key to do local verification of commits signed by Bitbucket.
The GPG key is available to download at:
{bitbucket}/signing/system-public-key.gpgRotate the system GPG key
As a result of rotating the system GPG key, a new key will be generated. You might need it to troubleshoot issues with signing system commits.
To rotate the system GPG key:
Stop Bitbucket. If you’re using a clustered instance, stop all nodes in the cluster.
Delete the following files from the Bitbucket shared home directory:
{Bitbucket shared home}/config/secret-system-signing-key.asc{Bitbucket shared home}/config/upgrades/core-system-signing-secret-key
Restart Bitbucket.
When Bitbucket is restarted, a new GPG key will be generated and used for commit signing and verification.
After you rotate the system GPG key, previously signed system commits will remain signed and verified but they will display the fingerprint of the previous system key.
Disable signed system commits
You need to be a system administrator to configure signed system commits.
To turn off signed system commits:
Go to Global administration > Signed system commits.
Select Off.
Select Save.
After the feature is disabled, previously created system commits will remain signed and verified. If the feature is re-enabled, the same GPG key will be used for commit signing unless it's rotated.
As a system administrator, you can disable signed system commits instance-wide through the Bitbucket properties file. To find out how to do this, look for feature.system.signed.git.objects in Configuration properties.
What if Bitbucket fails to sign system commits?
System commits won’t be signed in the following known cases:
Case #1: An error occurs when a commit is created on your behalf
The following error can display when Bitbucket creates a system commit on your behalf:
“Bitbucket couldn’t sign your commits with the system signing key. Contact your administrator to check the logs for more details.“
If system commits can’t be signed when you’re trying to merge a pull request or make an in-browser edit, check Mesh logs (depending on where your repository is located, you should check either the sidecar logs or external Mesh logs).
Case #2: The system GPG key can’t be loaded
When there’s an issue with loading the GPG key for signing system commits, Bitbucket will fail to start. In this case, the following error will display:
“Signing of system created Git objects is enabled but there was an issue loading the signing key. Please see the logs for more details.“
In this case, the issue might be with the key file. To find out more, check the application logs.
Here’s an example of how Bitbucket will log issues with the key file:
The signing key file could not be found - {Bitbucket shared home}/shared/config/secret-system-signing-key.ascRotating the system GPG key might be required to resolve the issue.
Case #3: mesh.enabled=false
Bitbucket won’t sign system commits when repositories are located in the shared home and the sidecar is disabled. That is when mesh.enabled=false. Signed system commits are only supported when using either the sidecar or external Mesh nodes.
To have system commits auto-signed, check your Bitbucket configuration and make sure that mesh.enabled is set to true. After that, restart Bitbucket.
Case #4: You’re using a rebase merge strategy
When you’re using a rebase merge strategy (Rebase and merge or Rebase and fast-forward), system commits won’t be signed even if the feature has been enabled.
When you use one of these options, Bitbucket commits from the source branch to the target branch, generating a new non-merge commit for each incoming commit. Non-merge commits use the content and data of the original commits. That is, Bitbucket doesn’t actually create non-merge commits and therefore, can’t sign them.
To fix this issue, you can rebase and merge locally, and then push the changes to the target branch. For more details, check Pull request merge strategies.
If you need more information or help with these or other issues, contact Atlassian Support.