How to use a signed tag in pull requests

After preparing her work to be pulled, the contributor uses git tag -s to create a signed tag:

Note that this example uses the -m option to create a signed tag with just a one-liner message, but this is for illustration purposes only. It is advisable to compose a well-written explanation of what the topic does to justify why it is worthwhile for the integrator to pull it, as this message will eventually become part of the final history after the integrator responds to the pull request (as we will see later).

Then she pushes the tag out to her public repository:

There is no need to push the work branch or anything else.

Note that the above command line used a plus sign at the beginning of +frotz-for-xyzzy to allow forcing the update of a tag, as the same contributor may want to reuse a signed tag with the same name after the previous pull request has already been responded to.

The contributor then prepares a message to request a "pull":

The arguments are:

The resulting msg.txt file begins like so:

followed by a shortlog of the changes and a diffstat. Comparing this with the earlier illustration of the output from the traditional git request-pull command, the reader should notice that:

The latter is why the contributor would want to justify why pulling her work is worthwhile when creating the signed tag. The contributor then opens her favorite MUA, reads msg.txt, edits and sends it to her upstream integrator.

After receiving such a pull request message, the integrator fetches and integrates the tag named in the request, with:

This operation will always open an editor to allow the integrator to fine tune the commit log message when merging a signed tag. Also, pulling a signed tag will always create a merge commit even when the integrator does not have any new commit since the contributor’s work forked (i.e. fast forward), so that the integrator can properly explain what the merge is about and why it was made.

In the editor, the integrator will see something like this:

Notice that the message recorded in the signed tag "Completed frotz feature" appears here, and again that is why it is important for the contributor to explain her work well when creating the signed tag.

As usual, the lines commented with # are stripped out. The resulting commit records the signed tag used for this validation in a hidden field so that it can later be used by others to audit the history. There is no need for the integrator to keep a separate copy of the tag in his repository (i.e. git tag -l won’t list the frotz-for-xyzzy tag in the above example), and there is no need to publish the tag to his public repository, either.

After the integrator responds to the pull request and her work becomes part of the permanent history, the contributor can remove the tag from her public repository, if she chooses, in order to keep the tag namespace of her public repository clean, with:

The --show-signature option can be given to git log or git show and shows the verification status of the embedded signed tag in merge commits created when the integrator responded to a pull request of a signed tag.

A typical output from git show --show-signature may look like this:

There is no need for the auditor to explicitly fetch the contributor’s signature, or to even be aware of what tag(s) the contributor and integrator used to communicate the signature. All the required information is recorded as part of the merge commit.