diff --git a/.github/workflows/ci.md b/.github/workflows/ci.md
index e23874d7ac..f29ae442d4 100644
--- a/.github/workflows/ci.md
+++ b/.github/workflows/ci.md
@@ -6,23 +6,8 @@ At a high level, the CI process is:
 3. On all platforms, build the `unison-runtime` Racket program save the resulting binaries as build artifacts.
 
 ### `env` vars at the top of `CI.yaml`:
-Some version numbers that are used during CI:
-- `ormolu_version: "0.5.0.1"`
-- `racket_version: "8.7"`
-- `jit_version: "@unison/internal/releases/0.0.18"`
-
-Some cached directories:
-  - `ucm_local_bin` a temp path for caching a built `ucm`
-  - `jit_src_scheme` a temp path for caching generated jit sources
-  - `unison-jit-dist`
-  - `base-codebase` a codebase path for caching a codebase generated by `unison-src/builtin-tests/base.md`
-  - `unison_src_test_results` a temp path for caching the result of passing tests that depend on `unison-src/`, which includes:
-    - `round-trip-tests`
-    - `transcripts`
-    - `unison-src/builtin-tests/interpreter-tests.md`
 
-`jit_generator_os: ubuntu-20.04`
-  - afaik, the jit sources are generated in a platform-independent way, so we just choose one platform to generate them on.
+These variables pin some dependency versions, set up some directories to cache, etc. Please see the `env` section in [ci.yaml](./ci.yaml) for specifics.
 
 ### Cached directories:
 
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 55e88ddbaf..a9bf5c83e6 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -12,19 +12,26 @@ on:
   workflow_dispatch:
 
 env:
-  ormolu_version: 0.5.2.0
-  ucm_local_bin: ucm-local-bin
+  ## Some version numbers that are used during CI
+  ormolu_version: 0.7.2.0
   jit_version: "@unison/internal/releases/0.0.18"
+  runtime_tests_version: "@unison/runtime-tests/main"
+
+  ## Some cached directories
+  # a temp path for caching a built `ucm`
+  ucm_local_bin: ucm-local-bin
+  # a temp path for caching generated jit sources
   jit_src_scheme: unison-jit-src/scheme-libs/racket
   jit_dist: unison-jit-dist
-  jit_generator_os: ubuntu-20.04
-  runtime_tests_version: "@unison/runtime-tests/main"
+  # a codebase path for caching a codebase generated by `unison-src/builtin-tests/interpreter-tests.md`
   runtime_tests_codebase: "~/.cache/unisonlanguage/runtime-tests.unison"
-
   # locations of some files that will indicate whether we need to re-run certain steps
   transcript_test_results: transcript-test-results
   interpreter_test_results: interpreter-test-results
 
+  ## afaik, the jit sources are generated in a platform-independent way, so we choose one platform to generate them on.
+  jit_generator_os: ubuntu-20.04
+
 jobs:
   ormolu:
     runs-on: ubuntu-20.04