diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -2110,6 +2110,55 @@ At this point your work is now in your branch on +GitHub+ and you can share the link with other collaborators. +[[git-gpg-signing]] +=== Signing the commits, tags, and pushes, with GnuPG + +Git knows how to sign commits, tags, and pushes. +When you sign a Git commit or a tag, you can prove that the code you submitted came from you and wasn't altered while you were transferring it. +You also can prove that you submitted the code and not someone else. + +A more in-depth documentation on signing commits and tags can be found in the https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work[Git Tools - Signing Your Work] chapter of the Git's book. + +The rationale behind signing pushes can be found in the https://github.com/git/git/commit/a85b377d0419a9dfaca8af2320cc33b051cbed04[commit that introduced the feature]. + +The best way is to simply tell Git you always want to sign commits, tags, and pushes. +You can do this by setting a few configuration variables: + +[source,shell] +.... +% git config --add user.signingKey=LONG-KEY-ID +% git config --add commit.gpgSign=true +% git config --add tag.gpgSign=true +% git config --add push.gpgSign=if-asked +.... + +// push.gpgSign should probably be set to `yes` once we enable it, or be set with --global, so that it is enabled for all repositories. + +[NOTE] +====== +To avoid possible collisions, make sure you give a long key id to Git. +You can get the long id with: `gpg --list-secret-keys --keyid-format LONG`. +====== + +[TIP] +====== +To use specific subkeys, and not have GnuPG to resolve the subkey to a primary key, attach `!` to the key. +For example, to encrypt for the subkey `DEADBEEF`, use `DEADBEEF!`. +====== + +==== Verifying signatures + +Commit signatures can be verified by running either `git verify-commit `, or `git log --show-signature`. + +Tag signatures can be verifed with `git verity-tag `, or `git tag -v `. + +//// +Commented out for now until we decide what to do. + +Git pushes are a bit different, they live in a special ref in the repository. +TODO: write how to verify them + +//// [[vcs-history]] == Version Control History