howto/using-signed-tag-in-pull-request.txt

   1 From: Junio C Hamano <gitster@pobox.com>
   2 Date: Tue, 17 Jan 2011 13:00:00 -0800
   3 Subject: Using signed tag in pull requests
   4 Abstract: Beginning v1.7.9, a contributor can push a signed tag to her
   5  publishing repository and ask her integrator to pull it. This assures the
   6  integrator that the pulled history is authentic and allows others to
   7  later validate it.
   8 Content-type: text/asciidoc
   9
  10 How to use a signed tag in pull requests
  11 ========================================
  12
  13 A typical distributed workflow using Git is for a contributor to fork a
  14 project, build on it, publish the result to her public repository, and ask
  15 the "upstream" person (often the owner of the project where she forked
  16 from) to pull from her public repository. Requesting such a "pull" is made
  17 easy by the `git request-pull` command.
  18
  19 Earlier, a typical pull request may have started like this:
  20
  21 ------------
  22  The following changes since commit 406da78032179...:
  23
  24    Froboz 3.2 (2011-09-30 14:20:57 -0700)
  25
  26  are available in the Git repository at:
  27
  28    example.com:/git/froboz.git for-xyzzy
  29 ------------
  30
  31 followed by a shortlog of the changes and a diffstat.
  32
  33 The request was for a branch name (e.g. `for-xyzzy`) in the public
  34 repository of the contributor, and even though it stated where the
  35 contributor forked her work from, the message did not say anything about
  36 the commit to expect at the tip of the for-xyzzy branch. If the site that
  37 hosts the public repository of the contributor cannot be fully trusted, it
  38 was unnecessarily hard to make sure what was pulled by the integrator was
  39 genuinely what the contributor had produced for the project. Also there
  40 was no easy way for third-party auditors to later verify the resulting
  41 history.
  42
  43 Starting from Git release v1.7.9, a contributor can add a signed tag to
  44 the commit at the tip of the history and ask the integrator to pull that
  45 signed tag. When the integrator runs `git pull`, the signed tag is
  46 automatically verified to assure that the history is not tampered with.
  47 In addition, the resulting merge commit records the content of the signed
  48 tag, so that other people can verify that the branch merged by the
  49 integrator was signed by the contributor, without fetching the signed tag
  50 used to validate the pull request separately and keeping it in the refs
  51 namespace.
  52
  53 This document describes the workflow between the contributor and the
  54 integrator, using Git v1.7.9 or later.
  55
  56
  57 A contributor or a lieutenant
  58 -----------------------------
  59
  60 After preparing her work to be pulled, the contributor uses `git tag -s`
  61 to create a signed tag:
  62
  63 ------------
  64  $ git checkout work
  65  $ ... "git pull" from sublieutenants, "git commit" your own work ...
  66  $ git tag -s -m "Completed frotz feature" frotz-for-xyzzy work
  67 ------------
  68
  69 Note that this example uses the `-m` option to create a signed tag with
  70 just a one-liner message, but this is for illustration purposes only. It
  71 is advisable to compose a well-written explanation of what the topic does
  72 to justify why it is worthwhile for the integrator to pull it, as this
  73 message will eventually become part of the final history after the
  74 integrator responds to the pull request (as we will see later).
  75
  76 Then she pushes the tag out to her public repository:
  77
  78 ------------
  79  $ git push example.com:/git/froboz.git/ +frotz-for-xyzzy
  80 ------------
  81
  82 There is no need to push the `work` branch or anything else.
  83
  84 Note that the above command line used a plus sign at the beginning of
  85 `+frotz-for-xyzzy` to allow forcing the update of a tag, as the same
  86 contributor may want to reuse a signed tag with the same name after the
  87 previous pull request has already been responded to.
  88
  89 The contributor then prepares a message to request a "pull":
  90
  91 ------------
  92  $ git request-pull v3.2 example.com:/git/froboz.git/ frotz-for-xyzzy >msg.txt
  93 ------------
  94
  95 The arguments are:
  96
  97 . the version of the integrator's commit the contributor based her work on;
  98 . the URL of the repository, to which the contributor has pushed what she
  99   wants to get pulled; and
 100 . the name of the tag the contributor wants to get pulled (earlier, she could
 101   write only a branch name here).
 102
 103 The resulting msg.txt file begins like so:
 104
 105 ------------
 106  The following changes since commit 406da78032179...:
 107
 108    Froboz 3.2 (2011-09-30 14:20:57 -0700)
 109
 110  are available in the Git repository at:
 111
 112    example.com:/git/froboz.git tags/frotz-for-xyzzy
 113
 114  for you to fetch changes up to 703f05ad5835c...:
 115
 116    Add tests and documentation for frotz (2011-12-02 10:02:52 -0800)
 117
 118  -----------------------------------------------
 119  Completed frotz feature
 120  -----------------------------------------------
 121 ------------
 122
 123 followed by a shortlog of the changes and a diffstat.  Comparing this with
 124 the earlier illustration of the output from the traditional `git request-pull`
 125 command, the reader should notice that:
 126
 127 . The tip commit to expect is shown to the integrator; and
 128 . The signed tag message is shown prominently between the dashed lines
 129   before the shortlog.
 130
 131 The latter is why the contributor would want to justify why pulling her
 132 work is worthwhile when creating the signed tag.  The contributor then
 133 opens her favorite MUA, reads msg.txt, edits and sends it to her upstream
 134 integrator.
 135
 136
 137 Integrator
 138 ----------
 139
 140 After receiving such a pull request message, the integrator fetches and
 141 integrates the tag named in the request, with:
 142
 143 ------------
 144  $ git pull example.com:/git/froboz.git/ tags/frotz-for-xyzzy
 145 ------------
 146
 147 This operation will always open an editor to allow the integrator to fine
 148 tune the commit log message when merging a signed tag.  Also, pulling a
 149 signed tag will always create a merge commit even when the integrator does
 150 not have any new commit since the contributor's work forked (i.e. 'fast
 151 forward'), so that the integrator can properly explain what the merge is
 152 about and why it was made.
 153
 154 In the editor, the integrator will see something like this:
 155
 156 ------------
 157  Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/
 158
 159  Completed frotz feature
 160  # gpg: Signature made Fri 02 Dec 2011 10:03:01 AM PST using RSA key ID 96AFE6CB
 161  # gpg: Good signature from "Con Tributor <nitfol@example.com>"
 162 ------------
 163
 164 Notice that the message recorded in the signed tag "Completed frotz
 165 feature" appears here, and again that is why it is important for the
 166 contributor to explain her work well when creating the signed tag.
 167
 168 As usual, the lines commented with `#` are stripped out. The resulting
 169 commit records the signed tag used for this validation in a hidden field
 170 so that it can later be used by others to audit the history. There is no
 171 need for the integrator to keep a separate copy of the tag in his
 172 repository (i.e. `git tag -l` won't list the `frotz-for-xyzzy` tag in the
 173 above example), and there is no need to publish the tag to his public
 174 repository, either.
 175
 176 After the integrator responds to the pull request and her work becomes
 177 part of the permanent history, the contributor can remove the tag from
 178 her public repository, if she chooses, in order to keep the tag namespace
 179 of her public repository clean, with:
 180
 181 ------------
 182  $ git push example.com:/git/froboz.git :frotz-for-xyzzy
 183 ------------
 184
 185
 186 Auditors
 187 --------
 188
 189 The `--show-signature` option can be given to `git log` or `git show` and
 190 shows the verification status of the embedded signed tag in merge commits
 191 created when the integrator responded to a pull request of a signed tag.
 192
 193 A typical output from `git show --show-signature` may look like this:
 194
 195 ------------
 196  $ git show --show-signature
 197  commit 02306ef6a3498a39118aef9df7975bdb50091585
 198  merged tag 'frotz-for-xyzzy'
 199  gpg: Signature made Fri 06 Jan 2012 12:41:49 PM PST using RSA key ID 96AFE6CB
 200  gpg: Good signature from "Con Tributor <nitfol@example.com>"
 201  Merge: 406da78 703f05a
 202  Author: Inte Grator <xyzzy@example.com>
 203  Date:   Tue Jan 17 13:49:41 2012 -0800
 204
 205      Merge tag 'frotz-for-xyzzy' of example.com:/git/froboz.git/
 206
 207      Completed frotz feature
 208
 209      * tag 'frotz-for-xyzzy' (100 commits)
 210        Add tests and documentation for frotz
 211        ...
 212 ------------
 213
 214 There is no need for the auditor to explicitly fetch the contributor's
 215 signature, or to even be aware of what tag(s) the contributor and integrator
 216 used to communicate the signature.  All the required information is recorded
 217 as part of the merge commit.