From 840ef252940bbfff484d45a2f5393565235fe086 Mon Sep 17 00:00:00 2001
From: Jo Humphrey <31373245+jamdelion@users.noreply.github.com>
Date: Mon, 14 Oct 2024 16:32:01 +0100
Subject: [PATCH] [docs] Add how-to for creating a team secret (#3804)

---
 doc/how-to/how-to-add-a-secret.md      |  6 +++---
 doc/how-to/how-to-add-a-team-secret.md | 30 ++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 3 deletions(-)
 create mode 100644 doc/how-to/how-to-add-a-team-secret.md

diff --git a/doc/how-to/how-to-add-a-secret.md b/doc/how-to/how-to-add-a-secret.md
index 58b8f28bef..72332e6f66 100644
--- a/doc/how-to/how-to-add-a-secret.md
+++ b/doc/how-to/how-to-add-a-secret.md
@@ -9,13 +9,13 @@ This guide will demonstrate how to -
 
 ## Process
 
-**Setup**
+### Setup
 1. Generate a secret [using the existing process](how-to-generate-a-secret.md), or obtain one from a third-party integration
 2. Add to your local `.env` file for local development
    - Note: This file is never checked into our public repository and is listed in our `.gitignore` config
 3. Document the secret in `.env.example`
 
-**Docker Environments (Local development + Pizza environments)**
+### Docker Environments (Local development + Pizza environments)
 To pass a secret into our Docker Compose setup you will need to map it into the relevant container in `docker-compose.yml`. For example - 
 
 ```yml
@@ -35,7 +35,7 @@ When building Pizza environments for testing, GitHub actions access secrets via
 > Please be aware that if you are rotating secrets this may affect existing Pizzas which will need to be rebuilt. This can be done manually in GitHub by re-running the latest action associated with affected PRs.
 
 
-**AWS / Pulumi Environments (Staging + Production environments)**
+### AWS / Pulumi Environments (Staging + Production environments)
 Secrets for Staging and Production environment are not handled in `.env` files, and are set directly in Pulumi, our Infrastruture as Code (IaC) platform.
 
 These values are set using the [Pulumi CLI](https://www.pulumi.com/docs/reference/cli/)
diff --git a/doc/how-to/how-to-add-a-team-secret.md b/doc/how-to/how-to-add-a-team-secret.md
new file mode 100644
index 0000000000..a1cc1bfaf1
--- /dev/null
+++ b/doc/how-to/how-to-add-a-team-secret.md
@@ -0,0 +1,30 @@
+# How to add a team secret
+This document describes our processes for adding a new team secret to the PlanX application, e.g. Gov Pay API keys.
+
+This guide will demonstrate how to - 
+ - Encrypt a secret
+ - Store the encrypted secret in our database
+ - Verify that the encrypted secret matches the decrypted/raw version
+
+## Process
+
+### Obtain the secret
+1. Get the raw secret, e.g. you might have been sent it in an email from a council officer.
+
+### Get the encryption key
+1. In `/infrastructure/application`, run `pulumi config get encryption-key --stack production`.
+2. This should output the encryption key in the terminal.
+
+### Encrypt the secret
+1. In `/scripts/encrypt`, run the encryption script using the encryption key and raw secret that you obtained in the previous steps: `pnpm encrypt <encryption-key> <secret>`.
+2. This should output the encrypted secret in the terminal.
+3. It is useful to double check that the encryption was successful by running the decryption script and checking you get the same secret back: `pnpm decrypt <encryption-key> <encrypted_secret>`.
+
+### Update the database with the encrypted secret
+1. Go to our [production Hasura instance](hasura.editor.planx.uk).
+2. In the `team_integrations` table, find the row for the relevant team and paste the encrypted secret into the correct field (e.g. `production_govpay_secret`). 
+3. Press save!
+
+### Test
+
+You should now prompt the team representative (e.g. council officer) to test that the secret has been successfully updated, e.g. test a flow with GovPay.