From 4396dd09b5f6b05aa0341b0cfb559a835dca51e3 Mon Sep 17 00:00:00 2001
From: Tomas Kopecek <tkopecek@redhat.com>
Date: Jul 22 2020 03:49:38 +0000
Subject: doc: dist-repo and exporting repos


Fixes: https://pagure.io/koji/issue/1964

---

diff --git a/docs/source/exporting_repositories.rst b/docs/source/exporting_repositories.rst
new file mode 100644
index 0000000..6d38f52
--- /dev/null
+++ b/docs/source/exporting_repositories.rst
@@ -0,0 +1,26 @@
+======================
+Exporting repositories
+======================
+
+There are multiple ways how to export repositories from koji. In first place,
+koji is not a repository manager - it is a build system. anyway, due to
+architecture and build logic it know about some repositories, typically those
+needed to populate buildroots. These are stored at
+``<topdir>/repos/<tag_name>/<repo_id>`` and can be consumed by builders via
+http. Of course, other users can download them also. Anyway, these repos are by
+design not suited for distribution.
+
+Simplest way ho to create distribution-ready repo is to use ``koji dist-repo``
+command. It allows user with ``dist-repo`` permission (non-default requirements
+can be specified via :doc:`hub policy <defining_hub_policies>`. ``dist-repo``
+command takes two basic arguments, where first is the name of the tag, while
+second is signing key id. You can create also repositories from unsigned rpms by
+supplying non-sensual signing key and adding ``--allow-missing-signatures``.
+Further options can tell koji if debuginfo or source rpms are needed, if zck
+dictionaries or multilib support should be used, etc. Feel free to go through
+whole ``koji dist-repo --help``.
+
+If you're aiming to have more control about repositories, varieties of
+distribution flavours, etc. use `pungi <https://pagure.io/pungi/>`_ which can
+create whole composes and which uses koji for some of the subtasks. Pungi + koji
+is what Fedora currently uses for composes.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a7b3acb..3262ac8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -27,6 +27,7 @@ Contents
     external_repo_server_bootstrap
     image_build
     winbuild
+    exporting_repositories
     tag_inheritance
     misc
     release_notes/release_notes