feat: Enhance GitHub App integration with secret management and webhook handling

Author: ColinDaglish

.gitignore

@@ -299,8 +299,6 @@ vignettes/*.pdf
 # R Environment Variables
 .Renviron
 
-# pkgdown site
-docs/
 
 # translation temp files
 po/*~

cloudbuild.yaml

@@ -1,23 +1,40 @@
 steps:
   - name: gcr.io/cloud-builders/docker
-    args: ["build", "-t", "gcr.io/$PROJECT_ID/ons-github-app:$COMMIT_SHA", "."]
+    args: ["build", "-t", "gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA", "."]
   - name: gcr.io/cloud-builders/docker
-    args: ["push", "gcr.io/$PROJECT_ID/ons-github-app:$COMMIT_SHA"]
+    args: ["push", "gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA"]
+  - name: gcr.io/google.com/cloudsdktool/cloud-sdk
+    entrypoint: bash
+    args:
+      - -eu
+      - -c
+      - |
+        if [[ -z "${_GITHUB_APP_ID}" ]]; then
+          echo "ERROR: Missing required substitution _GITHUB_APP_ID (your GitHub App ID)."
+          echo "Set it on your trigger or pass: gcloud builds submit --substitutions=_GITHUB_APP_ID=123456"
+          exit 1
+        fi
   - name: gcr.io/google.com/cloudsdktool/cloud-sdk
     entrypoint: gcloud
     args:
       - run
       - deploy
       - "${_SERVICE_NAME}"
       - --image
-      - "gcr.io/$PROJECT_ID/ons-github-app:$COMMIT_SHA"
+      - "gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA"
       - --region
       - "${_REGION}"
       - --platform
       - managed
-      - --allow-unauthenticated
+      - --set-env-vars
+      - "GITHUB_APP_ID=${_GITHUB_APP_ID},GITHUB_ACCEPTED_EVENTS=pull_request,GITHUB_PRIVATE_KEY_FILE=/var/secrets/github_private_key,GITHUB_WEBHOOK_SECRET_FILE=/var/secrets/github_webhook_secret"
+      - --secret
+      - github-app-private-key=/var/secrets/github_private_key
+      - --secret
+      - github-webhook-secret=/var/secrets/github_webhook_secret
 substitutions:
   _SERVICE_NAME: ons-github-app
   _REGION: europe-west2
+  _GITHUB_APP_ID: ""
 images:
-  - "gcr.io/$PROJECT_ID/ons-github-app:$COMMIT_SHA"
+  - "gcr.io/$PROJECT_ID/${_SERVICE_NAME}:$COMMIT_SHA"

deploy.sh

@@ -4,6 +4,9 @@ set -euo pipefail
 : "${PROJECT_ID:?Set PROJECT_ID}"
 : "${SERVICE_NAME:=ons-github-app}"
 : "${REGION:=europe-west2}"
+: "${GITHUB_APP_ID:?Set GITHUB_APP_ID}"
+
+: "${GITHUB_ACCEPTED_EVENTS:=pull_request}"
 
 IMAGE="gcr.io/${PROJECT_ID}/${SERVICE_NAME}:latest"
 
@@ -13,4 +16,6 @@ gcloud run deploy "${SERVICE_NAME}" \
   --image "${IMAGE}" \
   --region "${REGION}" \
   --platform managed \
-  --allow-unauthenticated
+  --set-env-vars "GITHUB_APP_ID=${GITHUB_APP_ID},GITHUB_ACCEPTED_EVENTS=${GITHUB_ACCEPTED_EVENTS},GITHUB_PRIVATE_KEY_FILE=/var/secrets/github_private_key,GITHUB_WEBHOOK_SECRET_FILE=/var/secrets/github_webhook_secret" \
+  --secret github-app-private-key=/var/secrets/github_private_key \
+  --secret github-webhook-secret=/var/secrets/github_webhook_secret

docs/tutorial/01-prereqs.md

@@ -0,0 +1,59 @@
+# 01 — Prerequisites and repo overview
+
+## Prerequisites
+
+You need:
+
+- A GCP project with billing enabled.
+- `gcloud` installed and authenticated (`gcloud auth login`).
+- Terraform >= 1.6.
+- Docker (and ideally Buildx for `linux/amd64` builds).
+- A GitHub account that can create and install GitHub Apps on the target org/user.
+
+Recommended:
+
+- `pre-commit` installed.
+- Permissions in GCP to create Cloud Run, API Gateway, Artifact Registry, Secret Manager secrets, IAM bindings, and KMS keys.
+
+## Repo overview (what code does what)
+
+### Runtime (FastAPI)
+
+- `src/app.py`
+  - `POST /webhooks/github` is the GitHub webhook endpoint.
+  - Verifies the webhook signature.
+  - Handles `pull_request.opened` by posting a comment back on the PR.
+  - `GET /healthz` is a health check.
+
+- `src/webhook.py`
+  - Computes an HMAC SHA-256 digest of the request body using the webhook secret.
+  - Compares it to the `X-Hub-Signature-256` header.
+
+- `src/github_app.py`
+  - Creates a GitHub App JWT (signed with the app’s private key).
+  - Exchanges it for an **installation access token**.
+  - Uses the installation token to call GitHub’s API (post PR comment).
+
+### Secrets strategy (best practice)
+
+- **Local dev**: you can pass secrets via environment variables (e.g. `docker run --env-file .env ...`).
+- **Cloud Run**: secrets should not be plain env vars.
+  - Store secret values in **Secret Manager**.
+  - Mount them into the container as **files**.
+  - The app reads them via:
+    - `GITHUB_PRIVATE_KEY_FILE`
+    - `GITHUB_WEBHOOK_SECRET_FILE`
+
+This keeps secret values out of container images, build logs, and Terraform state.
+
+## Install and run repo tooling (optional but recommended)
+
+From the repo root:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install pre-commit
+pre-commit install
+```

docs/tutorial/02-remote-state.md

@@ -0,0 +1,60 @@
+# 02 — Remote state bootstrap (GCS + KMS)
+
+Terraform state should be stored remotely so it’s durable, shareable, and can be locked.
+This repo includes an opinionated bootstrap module under `infra/remote-state/`.
+
+## What this step creates
+
+- Enables:
+  - Cloud Storage API
+  - Cloud KMS API
+  - IAM API
+- A KMS key ring + crypto key (used to encrypt Terraform state)
+- A GCS bucket for Terraform remote state
+
+## Steps
+
+1) Choose your project and principals
+
+You need:
+
+- `PROJECT_ID` — your GCP project
+- A principal to **read** state objects (viewer)
+- A principal to **write** state objects (admin)
+
+Examples of principals:
+
+- `user:you@example.com`
+- `serviceAccount:ci@your-project.iam.gserviceaccount.com`
+
+2) Create a `terraform.tfvars`
+
+In `infra/remote-state/`, create `terraform.tfvars`:
+
+```hcl
+project_id                     = "<your-project-id>"
+storage_object_viewer_principal = "user:you@example.com"
+storage_object_admin_principal  = "user:you@example.com"
+```
+
+3) Apply the bootstrap
+
+```bash
+cd infra/remote-state
+terraform init
+terraform apply
+```
+
+4) Capture outputs
+
+Terraform will output:
+
+- `state_bucket_name`
+- `kms_key_resource_name`
+
+You’ll use these in the next tutorial.
+
+## Why this matters for your workflow
+
+- Remote state enables safe collaboration and reduces the risk of state loss.
+- KMS encryption ensures sensitive metadata in state is encrypted at rest.

docs/tutorial/03-github-app.md

@@ -0,0 +1,63 @@
+# 03 — Create and configure the GitHub App
+
+## What you’re setting up
+
+A GitHub App that:
+
+- Receives `pull_request` webhooks
+- Uses an app private key to authenticate as the GitHub App
+- Uses an **installation token** to comment on PRs
+
+## Steps (GitHub UI)
+
+1) Create a new GitHub App
+
+- GitHub → Settings → Developer settings → GitHub Apps → **New GitHub App**
+
+2) Basic settings
+
+- **GitHub App name**: choose a unique name
+- **Homepage URL**: any valid URL (can be placeholder)
+
+3) Webhook settings
+
+- **Webhook URL**: set a placeholder for now (you will update it after Terraform deploy)
+  - Example placeholder: `https://example.com/webhooks/github`
+- **Webhook secret**: generate one and save it (you’ll store it in Secret Manager)
+
+Generate a webhook secret locally:
+
+```bash
+openssl rand -hex 32
+```
+
+4) Permissions (minimum for “comment on PR opened”)
+
+The app posts PR comments via the Issues Comments API (PRs are Issues underneath), so it needs:
+
+- **Repository permissions**
+  - Metadata: **Read-only** (required by GitHub)
+  - Issues: **Read & write** (to create PR comments)
+  - Pull requests: **Read-only** (webhook payload context)
+
+5) Subscribe to events
+
+- Subscribe to: **Pull request** events
+
+6) Create the App and generate a private key
+
+- Create the app
+- In the app settings page, generate a private key
+- Download the `.pem` file
+
+7) Install the App
+
+- Install the app on your org/user
+- Select the repository you want it to operate on
+
+## Values you will need later
+
+- **App ID** (used as `GITHUB_APP_ID`)
+- **Webhook secret** (store in Secret Manager)
+- **Private key file** (store in Secret Manager)
+- **Installation** is included in webhook payloads (the app uses it automatically)