Signing Commits
All commits merged into Brigade’s main
branch MUST bear two types of
signatures from the contributor who authored them – one being necessary per
CNCF, which governs the Brigade project, and the other
necessary for assurances of every commit’s origin.
⚠️ While this document discusses the signature requirements for commits made to Brigade, these requirements are equally applicable to all other repositories owned by the @brigadecore GitHub org.
⚠️ If you prefer learning through video, check out the video adaptation of this guide on our YouTube channel.
DCO Sign-Off
A DCO (Developer Certificate of Origin) sign-off is a line placed at the end of a commit message containing a contributor’s “signature.” In adding this, the contributor certifies that they have the right to contribute the material in question.
Here are the steps to sign your work:
-
Verify the contribution in your commit complies with the terms of the DCO.
-
Add a line like the following to your commit message:
Signed-off-by: Joe Smith <joe.smith@example.com>
You MUST use your legal name – handles or other pseudonyms are not permitted.
While you could manually add DCO sign-off to every commit, there is an easier way:
-
Configure your git client appropriately. This is one-time setup.
$ git config user.name <legal name> $ git config user.email <email address you use for GitHub>
If you work on multiple projects that require a DCO sign-off, you can configure your git client to use these settings globally instead of only for Brigade:
$ git config --global user.name <legal name> $ git config --global user.email <email address you use for GitHub>
-
Use the
--signoff
or-s
(lowercase) flag when making each commit. For example:$ git commit --message "<commit message>" --signoff
If you ever make a commit and forget to use the
--signoff
flag, you can amend your commit with this information before pushing:$ git commit --amend --signoff
-
You can verify the above worked as expected using
git log
. Your latest commit should look similar to this one:Author: Joe Smith <joe.smith@example.com> Date: Thu Feb 2 11:41:15 2018 -0800 Update README Signed-off-by: Joe Smith <joe.smith@example.com>
Notice the
Author
andSigned-off-by
lines match. If they do not, the PR will be rejected by the automated DCO check.
-
GPG Signature
While the DCO sign-off asserts a contributor’s right to make their contribution, the GPG signature is required to cryptographically offer a stronger assurance of the contributor’s identity.
Since the rationale for this requirement may be non-obvious, a brief justification may be in order. Strong assurances of the identity of every commit’s author may, after all, seem superfluous since pushing commits to GitHub already requires authentication. This would be true if not for the fact that authenticated users can also push commits authored by others. This can occur, for instance, in a scenario where multiple contributors have collaborated on a PR. Requiring every commit to be signed individually by an author known to GitHub ensures that the progeny of every single commit is known and traceable to a GitHub user.
Here is a summary of the steps required to sign your work. Most of this is one-time setup.
More extensive documentation of this subject is available from GitHub.
⚠️ The steps below cover a minimally-viable setup for cryptographically signing commits. User who are very serious about guarding their digital identity may wish to research this topic further and consider measures up to and including generating keys on an air-gapped machine, but these precautions are well beyond the scope of this documentation.
-
If you do not already have them, download and install the GPG command line tools for your operating system. Note that these tools may also be available as system packages.
-
If
gpg
was already installed, list available keys:$ gpg --list-secret-keys --keyid-format LONG
If you wish to use one of these keys, skip the next step.
-
For
gpg
versions 2.1.17 or greater, use the following command and then follow the prompts. You should generate an RSA key with a length of at 4096 bits.$ gpg --full-generate-key
If your
gpg
version is less than 2.1.17, use the following command instead:$ gpg --default-new-key-algo rsa4096 --gen-key
Now that your new key has been generated, re-list available keys as in the previous step:
$ gpg --list-secret-keys --keyid-format LONG
-
Identify the ID of the key you wish to use for cryptographically signing your commits. Copy this value.
In the example below, the key ID is
3AA5C34371567BD2
(found on the line beginning withsec
):$ gpg --list-secret-keys --keyid-format LONG /Users/hubot/.gnupg/secring.gpg ------------------------------------ sec 4096R/3AA5C34371567BD2 2016-03-10 [expires: 2017-03-10] uid Hubot ssb 4096R/42B317FD4BA89E7A 2016-03-10
-
Configure your git client to use the desired key:
$ git config user.signingkey <key id>
If you work on multiple projects that require cryptographically signed commits, you can configure your git client to use this setting globally instead of only for Brigade repositories:
$ git config --global user.signingkey <key id>
-
Next associate this new key with your GitHub account.
-
Export the public half of the key:
$ gpg --armor --export <key id>
-
Copy the public key, beginning with
-----BEGIN PGP PUBLIC KEY BLOCK-----
and ending with-----END PGP PUBLIC KEY BLOCK-----
. -
Visit https://github.com/settings/keys and click New GPG key and follow the prompts.
-
-
With all setup, up to this point, being one-time setup, all that remains is to cryptographically sign every commit you contribute to the Brigade project. Automation will reject pull requests containing any commits that are not cryptographically signed.
Cryptographically signing your commits can be accomplished with similar ease to adding the DCO signature. Simply use the
--gpg-sign
or-S
(uppercase) flag:$ git commit --message "<commit message>" --gpg-sign
If you ever make a commit and forget to use the
--gpg-sign
flag, you can amend your commit with this information before pushing:$ git commit --amend --gpg-sign
Recalling that DCO sign-off is also required, the full command to satisfy all signing requirements is:
$ git commit --message "<commit message>" --signoff --gpg-sign
Or more succinctly:
$ git commit --message "<commit message>" -s -S
Lastly, if you wish to cryptographically sign all commits for a Brigade repository, you may spare yourself from having to remember the
-S
flag by signing all commits by default:$ git config commit.gpgSign true
Or to enable this globally:
$ git config --global commit.gpgSign true
⚠️ No similar option exists for automating DCO sign-off, since DCO sign-off requires an explicit, per-commit attestation that the contributor has a right to contribute the material in question.