diff --git a/docs/admins/cicd-github-actions.qmd b/docs/admins/cicd-github-actions.qmd
index 7f29b1868..03353d051 100644
--- a/docs/admins/cicd-github-actions.qmd
+++ b/docs/admins/cicd-github-actions.qmd
@@ -13,10 +13,10 @@ These workflows are stored in the DataHub repo in the
 
 The basic order of operations is as follows:
 
-1. PR is created in the datahub repo.
+1. A pull request is created in the datahub repo.
 1. The labeler workflow applies labels based on the [file type and/or location](https://github.com/berkeley-dsep-infra/datahub/blob/staging/.github/labeler.yml).
-1. On PR merge to staging, if the labels match any hub, support or node placeholder deployments those specific systems are deployed.
-1. On PR merge to prod, only hubs are deployed (again based on labels).
+1. When the pull request is merged to `staging`, if the labels match any hub, support or node placeholder deployments those specific systems are deployed.
+1. When the pull request is merged to prod, only the hubs that have been modified are deployed (again based on labels).
 
 The hubs are deployed via [hubploy](https://github.com/berkeley-dsep-infra/hubploy),
 which is our custom wrapper for `gcloud`, `sops` and `helm`.
@@ -117,6 +117,31 @@ a list of what's to be deployed.
 That list is iterated over, and [hubploy](https://github.com/berkeley-dsep-infra/hubploy)
 is used to deploy only the flagged hubs.
 
+
+```{mermaid}
+%% State diagram documentation at
+%% https://mermaid.js.org/syntax/stateDiagram.html
+
+stateDiagram-v2
+    image_repo: github.com/berkeley-dsep-infra/hubname-user-image
+    forked_repo: github.com/github username/hubname-user-image
+    image_test_build: Image is built and tested
+    image_push_build: Image is built and pushed to registry
+    pr_created: A pull request is automatically<br/>created in the Datahub repo
+    deploy_to_staging: Hub is deployed to staging
+    contributor_tests: The contributor logs into the<br/>staging hub and tests the image.
+    deploy_to_prod: Hub is deployed to prod
+
+    image_repo --> forked_repo: Contributor forks the image repo.
+    forked_repo --> image_repo: Contributor creates a PR.
+    image_repo --> image_test_build
+    image_test_build --> image_push_build: Test build passes and Datahub staff merge pull request
+    image_push_build --> pr_created
+    pr_created --> deploy_to_staging: Datahub staff review and merge to staging
+    deploy_to_staging --> contributor_tests
+    contributor_tests --> deploy_to_prod: Datahub staff create a PR to merge to prod
+```
+
 #### Support and node-placeholder charts
 
 Each of these deployments has their own workflow, which only runs on pushes to