docs: add github setup

docs/admin/conf.rst

@@ -1,6 +1,13 @@
 Configuration File
 ==================
 
-A file named ``config.yaml`` must exist. For each provider in use, credentials must be added.
+A file named ``config.yaml`` must exist. For specifics about the provider configurations, see
+:doc:`External Services <external>`.
+
+Base Configuration
+------------------
+
+Template
+--------
 
 .. literalinclude:: ../../config.yaml.example

docs/admin/external.rst

@@ -0,0 +1,50 @@
+External Services
+=================
+
+Overview
+--------
+
+In order to deploy the circumvention resources, the following providers can be used:
+
++------------+-----+-------+---------+----------------+-----+
+| Resource   | AWS | Azure | Hetzner | GandiCloud VPS | OVH |
++============+=====+=======+=========+================+=====+
+| Web Proxy  | ✅  | ✅    | ❌      | ❌             | ❌  |
++------------+-----+-------+---------+----------------+-----+
+| Tor Bridge | ✅  | ❌    | ✅      | ✅             | ✅  |
++------------+-----+-------+---------+----------------+-----+
+
+Circumvention resource lists can be distributed via:
+
+* AWS S3
+* GitHub
+* GitLab
+
+GitHub
+------
+
+To configure GitHub, you will need a "personal access token".
+It is not possible to restrict a token to specific repositories, so it is best
+to create a
+`machine user <https://docs.github.com/en/developers/overview/managing-deploy-keys#machine-users>`_
+and then invite that user to only the repositories that should be accessed to
+limit the impact of a token disclosure.
+
+To create a token, visit the `New personal access token <https://github.com/settings/tokens/new>`_
+page of the GitHub settings.
+Add a note so that you will be reminded of the purpose of this token when you go to look at it later.
+The expiry can be set according to your threat model.
+GitHub will
+`send an email warning <https://github.blog/changelog/2021-07-26-expiration-options-for-personal-access-tokens/>`_
+before the token expires allowing you to generate a new token and update your configuration.
+
+Once you've generated your token, you can add it to your ``config.yaml``:
+
+.. code-block:: yaml
+
+   # GitHub
+   GITHUB_ACTIVATED: true
+   GITHUB_API_KEY: ghp_Sha8ShueNgihibai6soo1ojoo4aez0deo3bo
+
+The organisation, repository, filename and formats are all configured via the portal interface under
+:doc:`mirror lists <../user/lists>`.

docs/admin/index.rst

@@ -1,21 +0,0 @@
-Application Overview
-====================
-
-External Services
------------------
-
-In order to deploy the circumvention resources, the following providers can be used:
-
-+------------+-----+-------+---------+----------------+-----+
-| Resource   | AWS | Azure | Hetzner | GandiCloud VPS | OVH |
-+============+=====+=======+=========+================+=====+
-| Web Proxy  | ✅  | ✅    | ❌      | ❌             | ❌  |
-+------------+-----+-------+---------+----------------+-----+
-| Tor Bridge | ✅  | ❌    | ✅      | ✅             | ✅  |
-+------------+-----+-------+---------+----------------+-----+
-
-Circumvention resource lists can be distributed via:
-
-* GitHub
-* GitLab
-* AWS S3