diff --git a/.github/actions/setup-rust/CHANGELOG.md b/.github/actions/setup-rust/CHANGELOG.md
new file mode 100644
index 00000000..cfb45df0
--- /dev/null
+++ b/.github/actions/setup-rust/CHANGELOG.md
@@ -0,0 +1,13 @@
+
+# Changelog
+
+## v1.0.2
+
+- Document `BUILD_PROFILE` environment variable and fix README example
+
+## v1.0.1
+
+- Document caching requirements, limitations and clarify when caches are saved.
+
+## v1.0.0
+- Initial version.
diff --git a/.github/actions/setup-rust/README.md b/.github/actions/setup-rust/README.md
new file mode 100644
index 00000000..0e5298f7
--- /dev/null
+++ b/.github/actions/setup-rust/README.md
@@ -0,0 +1,59 @@
+# Setup Rust
+
+Install the Rust toolchain and cache your build dependencies. Optionally
+install PostgreSQL system libraries for crates that require them.
+
+## Inputs
+
+| Name | Description | Required | Default |
+| --- | --- | --- | --- |
+| install-postgres-deps | Install PostgreSQL system dependencies | no | `false` |
+| BUILD_PROFILE | Build profile used for caching | no | `release` |
+
+## Outputs
+
+None
+
+## Example
+
+```yaml
+uses: ./.github/actions/setup-rust@v1
+  with:
+    install-postgres-deps: true
+```
+
+## Caching
+
+This action caches `~/.cargo/registry`, `~/.cargo/git` and the build output in
+`target/$BUILD_PROFILE` using
+[actions/cache](https://github.com/actions/cache). The cache key combines the
+operating system, the `BUILD_PROFILE` environment variable and checksums of
+`rust-toolchain.toml` and any `Cargo.lock` files.
+
+The cache is restored when this step runs and is saved **after the entire job**
+finishes. Any files generated by subsequent build steps therefore become part of
+the cached directories.
+
+### Requirements
+
+- Set the `BUILD_PROFILE` environment variable (`debug` or `release`) before
+  invoking the action so that the cache key is deterministic.
+
+### Extent and limitations
+
+- GitHub limits the total cache size to 5 GB per repository and OS, so old
+  entries may be evicted.
+- Caches are scoped to the runner OS; Linux, macOS, and Windows caches are
+  independent.
+- The cache is best-effort: if the key changes or the cache is evicted, the
+  build will proceed without cached artifacts.
+
+### Effective use
+
+- Keep `rust-toolchain.toml` and `Cargo.lock` files checked in to ensure stable
+  cache keys.
+- Set `BUILD_PROFILE` consistently across jobs. For most CI runs, `release` is a
+  good choice.
+
+
+Release history is available in [CHANGELOG](CHANGELOG.md).