Merge pull request #333 from stackhpc/docs-secrets

docs: Add info about secrets and GitHub apps

Author: markgoddard

docs/usage/github-organisation-management.md

@@ -12,6 +12,8 @@ It is expected that all `plans` and `applies` are carried out within GitHub Acti
 
     Access to Terraform Cloud is limited due to team size restrictions if you need access to Terraform Cloud and don't have access already then feel free to request access in the appropriate Slack channel.
 
+GitHub authentication is handled using a GitHub app.
+
 ## Making Changes
 
 In this section we shall look at how you may modify the Terraform configuration to suit your needs and requirements.
@@ -181,3 +183,11 @@ Run the script to rename the repository. Note that this will directly update the
 ```
 
 Create a PR for the changes.
+
+## StackHPC Release Train TF bot
+
+GitHub authentication is handled using the [StackHPC Release Train TF bot App](https://github.com/organizations/stackhpc/settings/apps/stackhpc-release-train-tf-bot).
+This app has a private key that is registered as a [GitHub secret](secrets.md).
+The app is [installed](https://github.com/organizations/stackhpc/settings/installations/27194723) on the `stackhpc` organisation, with access to all repositories.
+It has only the necessary permissions, but these are rather broad.
+GitHub apps are documented [here](https://docs.github.com/en/apps/overview).

docs/usage/secrets.md

@@ -0,0 +1,14 @@
+# Secrets
+
+Various [GitHub Actions secrets](https://github.com/stackhpc/stackhpc-release-train/settings/secrets/actions) are used within StackHPC Release Train for integrating with external services.
+All secrets are scoped to the StackHPC Release Train repository unless stated otherwise.
+
+| Secret                           | Type                      | Owner                   | Description                                                                                         |
+| -------------------------------- | ------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
+| `ANSIBLE_VAULT_PASSWORD`         | Ansible vault password    | N/A                     | Ansible Vault password for StackHPC Release Train secrets.
+| `GALAXY_API_KEY`                 | Ansible Galaxy API token  | stackhpc-ci GitHub user | Organisation secret used for importing Ansible content into Ansible Galaxy.                         |
+| `repository_configuration_token` | GitHub PAT token          | stackhpc-ci GitHub user | Used in [source code CI](source-code-ci.md) to create GitHub pull requests.                         |
+|                                  |                           |                         | Used in [GitHub organisation management](github-organisation-management.md) to add comments to PRs. |
+| `SLACK_WEBHOOK_URL`              | Slack webhook URL         | Infra team leads        | Used to send Slack notifications on GitHub Actions workflow failures.                               |
+| `TF_API_TOKEN`                   | Terraform Cloud API token | Jack                    | Used in GitHub organisation management to authenticate with Terraform cloud.                        |
+| `TF_VAR_GITHUB_APP_PEM_FILE`     | GitHub app PEM file       | GitHub org admins       | Used in GitHub organisation management to authorise Terraform to manage GitHub repositories.        |

mkdocs.yml

@@ -26,6 +26,7 @@ nav:
       Access control: usage/access.md
       Source code CI: usage/source-code-ci.md
       GitHub Organisation Management: usage/github-organisation-management.md
+      Secrets: usage/secrets.md
       Notifications: usage/notifications.md
   - Operations:
       Ark: operations/ark.md