refs #42099

howto/git.md

@@ -35,25 +35,42 @@ pieces of information:
 With these, `sequoia-git` goes through commit by commit checking whether the
 signature is valid and authorized to perform operations.
 
-Note that, by default, `sequoia-git` will use the `openpgp-policy.toml` file in
-the root of the repo it's checking, but it can also perform the checks against
-an external policy file.
+By default, `sequoia-git` uses the `openpgp-policy.toml` file in the root of
+the repo being checked, but a path to an external policy file can be passed
+instead. In TPA, we do the former on the client side and the latter on the
+server side, as we'll see in the next section.
 
 ### The TPA setup
 
-In TPA we use one file to authenticate changes for all our repositories, namely
-the [`openpgp-policy.toml`][] file in the root of the Puppet repository. Using
-one centralized file allows for updating certificates and permissions in only
-one place and have it deployed to the relevant places.
+In TPA we use one OpenPGP policy file to authenticate changes for all our
+repositories, namely the [`openpgp-policy.toml`][] file in the root of the
+Puppet repository. Using one centralized file allows for updating certificates
+and permissions in only one place and have it deployed to the relevant places.
 
-The trust-root for the Puppet repos is stored both in [hiera data for the
-puppetserver role][] inside the Puppet repo (for deployment in servers) and in
-tpo/tpa/repos> (for configuration and verification in the client-side).
+For authenticating changes on the server-side:
 
+- the TPA OpenPGP policy file is deployed to
+  `/etc/openpgp-policy/policies/tpa.toml`,
+- trust-roots for the Puppet repos (stored in [hiera data for the puppetserver
+  role][] in the Puppet repo) are deployed to
+  `/etc/openpgp-policy/gitconfig/${REPO}.conf`, and
+- per-repo Git hooks use the above info to authenticate changes.
+
+On the client-side:
+
+- we use the TPA OpenPGP policy file in the root of the Puppet repo,
+- trust-roots are stored in the [`.mrconfig`][] file in tpo/tpa/repos> and set
+  as Git configs in the relevant repos by `mr update` (see [doc on
+  `repos.git`][]), and
+- per-repo Git hooks use the above info to authenticate changes.
+
+[`.mrconfig`]: https://gitlab.torproject.org/tpo/tpa/repos/-/blob/main/.mrconfig
 [hiera data for the puppetserver role]: https://gitlab.torproject.org/tpo/tpa/puppet-control/-/blob/production/data/roles/puppetserver.yaml
 
-When the trust-roots for these repositories change, they need to be updated in
-both places.
+Note: When the trust-root for a repository changes, it needs to be updated in
+the [hiera data for the puppetserver role][] and/or the [`.mrconfig`][] file,
+depending on whether it's supposed to be authenticated on server and/or client
+side.
 
 ### Authentication in the Puppet Server