From 6033e5ab8557ef40ecc1ceef1b5a338fce992ef0 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Wed, 23 Aug 2023 11:14:55 -0400
Subject: [PATCH] man: Describe GPG key behavior

Came up on chat, and this is important since it differs from
traditional `rpm/dnf` today.
---
 man/rpm-ostree.xml | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/man/rpm-ostree.xml b/man/rpm-ostree.xml
index dcf7e1974c..cf9efc38a3 100644
--- a/man/rpm-ostree.xml
+++ b/man/rpm-ostree.xml
@@ -897,6 +897,31 @@ $ systemctl start postgresql  # Some setup required
 
   </refsect1>
 
+  <refsect1>
+    <title>Repository configuration and GPG keys</title>
+
+    <para>
+      rpm-ostree uses the libdnf shared library, which honors <literal>/etc/yum.repos.d</literal>.
+      Note that rpm-md (yum/dnf) repositories are only checked if client-side package layering is
+      enabled.
+    </para>
+
+    <para>
+      However, the behavior for GPG keys is slightly different from a traditional <command>rpm</command>
+      system.  Essentially, all GPG keys in <literal>/etc/pki/rpm-gpg</literal> are loaded and trusted.
+      The <literal>.repo</literal> file should reference the file path in there.
+    </para>
+    <para>
+      The <literal>rpm --import /path/to/key.gpg</literal> command will not function today on a
+      live/booted system because rpm tries to write directly to the RPM database.
+    </para>
+
+    <para>
+      However, during a container build process, the RPM database is writable and such changes will
+      persist.
+    </para>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>