From cb3bae900f6c85d4529842bf75f3cca0b4bb1df7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= <ludo@gnu.org>
Date: Fri, 24 Jul 2020 17:44:20 +0200
Subject: [PATCH] doc: Mention the channel keyring branch.
Reported by Pierre Neidhardt <mail@ambrevar.xyz>.
* doc/guix.texi (Channels): Mention the keyring branch and the
'keyring-reference' bit in '.guix-channel'.
---
doc/guix.texi | 20 +++++++++++++++++++-
1 file changed, 19 insertions(+), 1 deletion(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index 0d090eef184..a6fc64bed8f 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4245,10 +4245,28 @@ time-machine}, the command looks up the introductory commit and verifies
that it is signed by the specified OpenPGP key. From then on, it
authenticates commits according to the rule above.
-To summarize, as the author of a channel, there are two things you have
+Additionally, your channel must provide all the OpenPGP keys that were
+ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
+files, which can be either binary or ``ASCII-armored''. By default,
+those @file{.key} files are searched for in the branch named
+@code{keyring} but you can specify a different branch name in
+@code{.guix-channel} like so:
+
+@lisp
+(channel
+ (version 0)
+ (keyring-reference "my-keyring-branch"))
+@end lisp
+
+To summarize, as the author of a channel, there are three things you have
to do to allow users to authenticate your code:
@enumerate
+@item
+Export the OpenPGP keys of past and present committers with @command{gpg
+--export} and store them in @file{.key} files, by default in a branch
+named @code{keyring} (we recommend making it an @dfn{orphan branch}).
+
@item
Introduce an initial @file{.guix-authorizations} in the channel's
repository. Do that in a signed commit (@pxref{Commit Access}, for
--
GitLab