From 7710a5bb3c927cf0d9ff5e9bfe143fd762f223bd Mon Sep 17 00:00:00 2001
From: Jesse London <jesselondon@gmail.com>
Date: Thu, 12 Nov 2020 15:07:34 -0600
Subject: [PATCH] documentation for CI/CD via GitHub Actions workflow

---
 .envrc.example | 15 +++++++++++++++
 README.md      | 12 ++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/.envrc.example b/.envrc.example
index e1c8dfb..e06db4e 100644
--- a/.envrc.example
+++ b/.envrc.example
@@ -31,6 +31,21 @@
 # export IMAGE_REPOSITORY_NAME=
 # export IMAGE_REPOSITORY_URI=XYZ.dkr.ecr.us-west-2.amazonaws.com
 
+# GitHub deployment
+#
+# Deployments of the app may be recorded to the GitHub API.
+#
+# The use of a personal access token is *strongly* encouraged over the
+# specification of your account password.
+#
+# This token requires only the "repo_deployment" scope for this
+# repository.
+#
+# See: https://github.com/settings/tokens
+#
+# export GITHUB_REPO=dssg/marketplace
+# export GITHUB_AUTH=user-name:auth-token
+
 # SSH
 #
 # In order to access the EC2 servers that make up the cluster, for
diff --git a/README.md b/README.md
index ea45a62..76b5c70 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,18 @@ The Web app binds to `localhost:8000`.
 
 ## Deployment
 
+### Automation
+
+The marketplace integrates with [GitHub Actions](https://github.com/dssg/marketplace/actions) for automated deployment via a [workflow named CI/CD](.github/workflows/build-deploy.yml).
+
+The CI/CD workflow is triggered by the publishing of a [GitHub Release](https://github.com/dssg/marketplace/releases). Only releases for semantically-named tags are considered for deployment. Tags of the form `[0-9].[0-9].[0-9]` will be built and deployed to both staging and production. Tags of the form `[0-9].[0-9]*` will be deployed to staging only. Releases for tags of any other form are ignored.
+
+The workflow executes the same `manage` commands as those outlined below for manual use.
+
+**Note**: The automated workflow *will not* instruct the deployment target to collect static assets nor to migrate the database. These tasks may be performed manually following an automated deployment; or, it is advised that such deployments be performed manually in their entirety.
+
+The below commands will, by default, [record the deployment with GitHub](https://api.github.com/repos/dssg/marketplace/deployments). Neither manual nor automated deployments against non-latest tags or already-deployed tags will succeed.
+
 ### Build for deployment
 
 To build the app's Docker image for deployment: