Documentation/howto/using-signed-tag-in-pull-request.txt - jrn/git - Git at Google

 From: Junio C Hamano <gitster@pobox.com>
 Date: Tue, 17 Jan 2011 13:00:00 -0800
 Subject: Using signed tag in pull requests
 Abstract: Beginning v1.7.9, a contributor can push a signed tag to her
  publishing repository and ask her integrator to pull it. This assures the
  integrator that the pulled history is authentic and allows others to
  later validate it.
 Content-type: text/asciidoc

 How to use a signed tag in pull requests
 ========================================

 A typical distributed workflow using Git is for a contributor to fork a
 project, build on it, publish the result to her public repository, and ask
 the "upstream" person (often the owner of the project where she forked
 from) to pull from her public repository. Requesting such a "pull" is made
 easy by the `git request-pull` command.

 Earlier, a typical pull request may have started like this:

 ------------
  The following changes since commit 406da78032179...:

    Froboz 3.2 (2011-09-30 14:20:57 -0700)

  are available in the Git repository at:

    example.com:/git/froboz.git for-xyzzy
 ------------

 followed by a shortlog of the changes and a diffstat.

 The request was for a branch name (e.g. `for-xyzzy`) in the public
 repository of the contributor, and even though it stated where the
 contributor forked her work from, the message did not say anything about
 the commit to expect at the tip of the for-xyzzy branch. If the site that
 hosts the public repository of the contributor cannot be fully trusted, it
 was unnecessarily hard to make sure what was pulled by the integrator was
 genuinely what the contributor had produced for the project. Also there
 was no easy way for third-party auditors to later verify the resulting
 history.

 Starting from Git release v1.7.9, a contributor can add a signed tag to
 the commit at the tip of the history and ask the integrator to pull that
 signed tag. When the integrator runs `git pull`, the signed tag is
 automatically verified to assure that the history is not tampered with.
 In addition, the resulting merge commit records the content of the signed
 tag, so that other people can verify that the branch merged by the
 integrator was signed by the contributor, without fetching the signed tag
 used to validate the pull request separately and keeping it in the refs
 namespace.

 This document describes the workflow between the contributor and the
 integrator, using Git v1.7.9 or later.


 A contributor or a lieutenant
 -----------------------------

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

 ------------
  $ git checkout work
  $ ... "git pull" from sublieutenants, "git commit" your own work ...
  $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work
 ------------

 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:

 ------------
  $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy
 ------------

 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":

 ------------
  $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt
 ------------

 The arguments are:

 . the version of the integrator's commit the contributor based her work on;
 . the URL of the repository, to which the contributor has pushed what she
   wants to get pulled; and
 . the name of the tag the contributor wants to get pulled (earlier, she could
   write only a branch name here).

 The resulting msg.txt file begins like so:

 ------------
  The following changes since commit 406da78032179...:

    Froboz 3.2 (2011-09-30 14:20:57 -0700)

  are available in the Git repository at:

    example.com:/git/froboz.git tags/frotz-for-xyzzy

  for you to fetch changes up to 703f05ad5835c...:

    Add tests and documentation for frotz (2011-12-02 10:02:52 -0800)

  -----------------------------------------------
  Completed frotz feature
  -----------------------------------------------
 ------------

 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 tip commit to expect is shown to the integrator; and
 . The signed tag message is shown prominently between the dashed lines
   before the shortlog.

 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.


 Integrator
 ----------

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

 ------------
  $ git pull example.com:/git/froboz.git/ tags/frotz-for-xyzzy
 ------------

 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:

 ------------
  Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/

  Completed frotz feature
  # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB
  # gpg: Good signature from "Con Tributor <nitfol@example.com>"
 ------------

 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:

 ------------
  $ git push example.com:/git/froboz.git :frotz-for-xyzzy
 ------------


 Auditors
 --------

 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:

 ------------
  $ git show --show-signature
  commit 02306ef6a3498a39118aef9df7975bdb50091585
  merged tag 'frotz-for-xyzzy'
  gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB
  gpg: Good signature from "Con Tributor <nitfol@example.com>"
  Merge: 406da78 703f05a
  Author: Inte Grator <xyzzy@example.com>
  Date:   Tue Jan 17 13:49:41 2012 -0800

      Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/

      Completed frotz feature

      * tag 'frotz-for-xyzzy' (100 commits)
        Add tests and documentation for frotz
        ...
 ------------

 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.
	From: Junio C Hamano <gitster@pobox.com>
	Date: Tue, 17 Jan 2011 13:00:00 -0800
	Subject: Using signed tag in pull requests
	Abstract: Beginning v1.7.9, a contributor can push a signed tag to her
	publishing repository and ask her integrator to pull it. This assures the
	integrator that the pulled history is authentic and allows others to
	later validate it.
	Content-type: text/asciidoc

	How to use a signed tag in pull requests
	========================================

	A typical distributed workflow using Git is for a contributor to fork a
	project, build on it, publish the result to her public repository, and ask
	the "upstream" person (often the owner of the project where she forked
	from) to pull from her public repository. Requesting such a "pull" is made
	easy by the `git request-pull` command.

	Earlier, a typical pull request may have started like this:

	------------
	The following changes since commit 406da78032179...:

	Froboz 3.2 (2011-09-30 14:20:57 -0700)

	are available in the Git repository at:

	example.com:/git/froboz.git for-xyzzy
	------------

	followed by a shortlog of the changes and a diffstat.

	The request was for a branch name (e.g. `for-xyzzy`) in the public
	repository of the contributor, and even though it stated where the
	contributor forked her work from, the message did not say anything about
	the commit to expect at the tip of the for-xyzzy branch. If the site that
	hosts the public repository of the contributor cannot be fully trusted, it
	was unnecessarily hard to make sure what was pulled by the integrator was
	genuinely what the contributor had produced for the project. Also there
	was no easy way for third-party auditors to later verify the resulting
	history.

	Starting from Git release v1.7.9, a contributor can add a signed tag to
	the commit at the tip of the history and ask the integrator to pull that
	signed tag. When the integrator runs `git pull`, the signed tag is
	automatically verified to assure that the history is not tampered with.
	In addition, the resulting merge commit records the content of the signed
	tag, so that other people can verify that the branch merged by the
	integrator was signed by the contributor, without fetching the signed tag
	used to validate the pull request separately and keeping it in the refs
	namespace.

	This document describes the workflow between the contributor and the
	integrator, using Git v1.7.9 or later.


	A contributor or a lieutenant
	-----------------------------

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

	------------
	$ git checkout work
	$ ... "git pull" from sublieutenants, "git commit" your own work ...
	$ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work
	------------

	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:

	------------
	$ git push example.com:/git/froboz.git/ +frotz-for-xyzzy
	------------

	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":

	------------
	$ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt
	------------

	The arguments are:

	. the version of the integrator's commit the contributor based her work on;
	. the URL of the repository, to which the contributor has pushed what she
	wants to get pulled; and
	. the name of the tag the contributor wants to get pulled (earlier, she could
	write only a branch name here).

	The resulting msg.txt file begins like so:

	------------
	The following changes since commit 406da78032179...:

	Froboz 3.2 (2011-09-30 14:20:57 -0700)

	are available in the Git repository at:

	example.com:/git/froboz.git tags/frotz-for-xyzzy

	for you to fetch changes up to 703f05ad5835c...:

	Add tests and documentation for frotz (2011-12-02 10:02:52 -0800)

	-----------------------------------------------
	Completed frotz feature
	-----------------------------------------------
	------------

	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 tip commit to expect is shown to the integrator; and
	. The signed tag message is shown prominently between the dashed lines
	before the shortlog.

	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.


	Integrator
	----------

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

	------------
	$ git pull example.com:/git/froboz.git/ tags/frotz-for-xyzzy
	------------

	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:

	------------
	Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/

	Completed frotz feature
	# gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB
	# gpg: Good signature from "Con Tributor <nitfol@example.com>"
	------------

	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:

	------------
	$ git push example.com:/git/froboz.git :frotz-for-xyzzy
	------------


	Auditors
	--------

	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:

	------------
	$ git show --show-signature
	commit 02306ef6a3498a39118aef9df7975bdb50091585
	merged tag 'frotz-for-xyzzy'
	gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB
	gpg: Good signature from "Con Tributor <nitfol@example.com>"
	Merge: 406da78 703f05a
	Author: Inte Grator <xyzzy@example.com>
	Date: Tue Jan 17 13:49:41 2012 -0800

	Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/

	Completed frotz feature

	* tag 'frotz-for-xyzzy' (100 commits)
	Add tests and documentation for frotz
	...
	------------

	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.