Merge pull request #156 from MITLibraries/build-documentation

Update documentation for build secrets

.github/README.md

@@ -227,19 +227,9 @@ This application uses a variety of ways to manage environment variables and secr
 
 ### Build secrets
 
-Managed with: [**Terminus Secrets Manager** plugin](https://github.com/pantheon-systems/terminus-secrets-manager-plugin)
+_Information about our build-related secret values has been moved to a separate How-to article:
+[How to manage secret values for automated builds and deploys](/docs/howto/manage-build-secrets.md)_
 
-Example: `terminus secret:list mitlib-wp-network`
-
-This tool allows us to provide secret values for use by Composer during application deploys.
-
-Please see the readme for that project for [installation](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#installation) and [usage](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#terminus-secrets-manager-commands) instructions.
-
-#### Required build secrets
-
-* `COMPOSER_AUTH` - License key necessary for installing the Advanced Custom Fields Pro plugin. Content can be found in
-  the official acf documentation `auth.json` file and just removing all the line breaks
-* `github-oauth.github.com` - User access token defined by the `mitlib-wp-network-deploy` account
 
 ### Application secrets
 
@@ -284,16 +274,6 @@ Bedrock makes use of an `.env` file to store environment variables. Pantheon tak
 - `COMPOSER_AUTH` A JSON formatted object that has one entry for the user access token defined by the `mitlib-wp-network-deploy` account, for installing forked plugins and an entry for our Advanced Custom Fields Pro authentication. [see Shared-Prod-Pantheon folder in lastpass for values and additional context for `auth.json` and `COMPOSER_AUTH`] [NOTE: composer does not read from .env so locally these also need to be in auth.json and kept out of version control]
   * composer will read an auth.json file in a user home directory or the root directory of the application. If using the application root, please ensure it is gitignored. Our lastpass should contain a current working version of what to put in auth.json (and if you make changes to auth.json locally, consisider whether they should also change in lastpass or in the CI and Pantheon equivalent which is `COMPOSER_AUTH`!)
 
-### Github secrets
-
-Managed with: Github web UI
-
-In addition to secret values stored using Terminus, we also define certain values used by our CI workflow using Github secrets.
-
-- `COMPOSER_AUTH` A JSON structure that has one entry for the user access token defined by the `mitlib-wp-network-deploy` account, for installing forked plugins and an entry for our Advanced Custom Fields Pro authentication. [see lastpass]
-- `DEPLOY_SSH_KNOWN_HOSTS` The known_hosts file to allow GitHubs' CI to trust the Pantheon git server.
-- `DEPLOY_SSH_PRIVATE_KEY` The private key (with blank passphrase) used to connect to Pantheon's git server. The public key is added to your personal settings within Pantheon.
-- `PANTHEON_REPOSITORY` The SSH-format address of the git repository in Pantheon.
 
 ---
 **The sections below were included in the original Readme, and I'm not sure whether they are still useful in this context.**

docs/howto/manage-build-secrets.md

@@ -0,0 +1,92 @@
+# How to manage secret values for automated builds and deploys
+
+This document describes how we manage secret values for use in automated builds.
+
+## Tooling required
+
+In order to work with these values, you will need:
+
+* [Composer](https://getcomposer.org), for local builds
+* Access to [the Actions secrets and variables page](https://github.com/MITLibraries/mitlib-wp-network/settings/secrets/actions) for this Github repository, for builds managed by Github Actions.
+* The [Terminus CLI tool](), including the [Secrets Manager plugin](https://github.com/MITLibraries/mitlib-wp-network/settings/secrets/actions), for builds managed by Pantheon.
+
+## The secrets needed
+
+In order to build the network correctly, all build systems will need to have access to two values:
+
+1. The license code for the Advanced Custom Fields plugin.
+2. A Github "classic" token with repository scope, managed by the `mitlib-wp-network-deploy` user, for access to some
+   private repositories.
+
+Both current values can be found in the MIT Libraries' shared LastPass account, in the `Shared-Product-Pantheon` folder.
+The user credentials for the deploy user are also in that folder.
+
+The Github token is currently set to expire every 90 days. New values can be generated by logging into that account and
+going to [the Classic Tokens page](https://github.com/settings/tokens) within the Developer settings.
+
+**When you make a new token, your first step should be to save the new value in LastPass, before updating anything else.**
+
+For builds on Github, the following additional values are needed:
+
+3. A known_hosts file for deploying from Github to Pantheon.
+4. An SSH private key for deploying from Github to Pantheon.
+5. The SSH-format address of the Pantheon git repository.
+
+
+## The build processes
+
+Working with the WordPress network involves a few different automated build processes, and each requires these two
+values to be stored in slightly different ways.
+
+### Local builds
+
+Your local Composer installation will build the network when you are working locally. Composer stores its secrets in an
+`auth.json` file within your user profile, and it will manage the file on its own. If updates are needed, it will prompt
+you for the new value.
+
+### Github builds
+
+We have a handful of automated checks within Github Actions, which run for every pull request. Additionally, there is a
+deploy workflow which pushes the `master` branch to the Dev tier within Pantheon when a PR merges.
+
+These workflows require the following secrets to be defined:
+
+* `ACF_PRO_KEY` - The license file on its own.
+* `COMPOSER_AUTH` - A JSON structure which combines the ACF key and the token (the format for this value is provided in
+  LastPass).
+* `DEPLOY_SSH_KNOWN_HOSTS` - The known_hosts file to allow Github's CI to trust the Pantheon git server.
+* `DEPLOY_SSH_PRIVATE_KEY` - The private key (with blank passphrase) used to connect to Pantheon's git server. The
+  public key is added to your personal settings within Pantheon.
+* `PANTHEON_REPOSITORY` - The SSH-format address of the git repository in Pantheon.
+
+These values can be defined, but not read, using [the Actions secrets and variables page](https://github.com/MITLibraries/mitlib-wp-network/settings/secrets/actions) within this repository.
+
+### Pantheon builds
+
+The Pantheon platform builds the WordPress application when deploying changes to any tier, including setting up new
+multidev instances and promoting changes to production.
+
+Managing these values within Pantheon is done via the Terminus
+[Secrets Manager plugin](https://github.com/MITLibraries/mitlib-wp-network/settings/secrets/actions).
+Please see the readme for that project for
+[installation](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#installation) and 
+[usage](https://github.com/pantheon-systems/terminus-secrets-manager-plugin#terminus-secrets-manager-commands) instructions.
+
+There are three values defined by this plugin.
+
+* `ACF_PRO_KEY` - The license file on its own. This is an `env` type secret, with a scope of `ic`.
+* `COMPOSER_AUTH` - A JSON structure which combines the ACF key and the token (the format for this value is provided in
+  LastPass). This is an `env` type secret, with a scope of `ic, user`.
+* `github-oauth.github.com` - The Github classic token on its own. This is a `composer` type secret, with a scope of
+  `user, ic`.
+
+The current configuration of these values can be seen via:
+
+```bash
+% terminus secret:list mitlib-wp-network
+ ------------- ------------- ------------------------------------------------------------------------- --------------- 
+  Secret name   Secret type   Secret value                                                              Secret scopes  
+ ------------- ------------- ------------------------------------------------------------------------- --------------- 
+  ...           ...           ...                                                                       ...
+ ------------- ------------- ------------------------------------------------------------------------- --------------- 
+ ```