git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
e9ad0b4ff8e0a6548a8deddb4730cd8b11815c26 blob 8315 bytes (raw)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
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 their
 publishing repository and ask their 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 their public repository, and ask
the "upstream" person (often the owner of the project where they forked
from) to pull from their 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 their 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 their 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 they push the tag out to their 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 their work on;
. the URL of the repository, to which the contributor has pushed what they
  want to get pulled; and
. the name of the tag the contributor wants to get pulled (earlier, they 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 their favorite MUA, reads msg.txt, edits and sends it to their 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 their 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 their
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 their public
repository, either.

After the integrator responds to the pull request and their work becomes
part of the permanent history, the contributor can remove the tag from
their public repository, if they choose, in order to keep the tag namespace
of their 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.
debug log:

solving e9ad0b4ff8e0 ...
found e9ad0b4ff8e0 in https://public-inbox.org/git/afc51c5e6edec7935a6d0d0a05d396e11311ca6c.1623085069.git.gitgitgadget@gmail.com/
found bbf040eda8af in https://80x24.org/mirrors/git.git
preparing index
index prepared:
100644 bbf040eda8aff01e4fd064b3008d8565462898d9	Documentation/howto/using-signed-tag-in-pull-request.txt

applying [1/1] https://public-inbox.org/git/afc51c5e6edec7935a6d0d0a05d396e11311ca6c.1623085069.git.gitgitgadget@gmail.com/
diff --git a/Documentation/howto/using-signed-tag-in-pull-request.txt b/Documentation/howto/using-signed-tag-in-pull-request.txt
index bbf040eda8af..e9ad0b4ff8e0 100644

Checking patch Documentation/howto/using-signed-tag-in-pull-request.txt...
Applied patch Documentation/howto/using-signed-tag-in-pull-request.txt cleanly.

index at:
100644 e9ad0b4ff8e0a6548a8deddb4730cd8b11815c26	Documentation/howto/using-signed-tag-in-pull-request.txt

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).