hoverkraft-tech · neilime · Jun 30, 2026 · Jun 30, 2026
diff --git a/application/docs/methodology/best-practices/ci-cd/cicd-release-management.md b/application/docs/methodology/best-practices/ci-cd/cicd-release-management.md
@@ -231,6 +231,12 @@ feat!: remove deprecated API         → MAJOR bump
 
 **Automated Versioning:**
 
+:::tip Pin real workflow refs with Ratchet
+This example uses a readable tag for clarity. In a real repository, run [Pin
+workflow refs with Ratchet](./github-actions/pinning-with-ratchet.md) on your
+workflow files and commit the rewritten SHA pins.
+:::
+
 ```yaml
 # .github/workflows/release.yml
 - name: Semantic Release

diff --git a/application/docs/methodology/best-practices/ci-cd/github-actions/index.md b/application/docs/methodology/best-practices/ci-cd/github-actions/index.md
@@ -78,10 +78,17 @@ Treat Actions dependencies as executable third-party code. A compromised action
 read the repository checkout, inspect runner files, access available secrets, and
 use granted token permissions.
 
+When you need the latest safe pin for a workflow ref, start from a readable
+version such as `@v4`, then use [Pin workflow refs with
+Ratchet](./pinning-with-ratchet.md) to rewrite it to a full SHA and keep the
+generated `# ratchet:` constraint comment so later `ratchet update` runs remain
+predictable.
+
 ✅ **DO**:
 
 - Pin third-party actions and reusable workflows to full-length commit SHAs.
 - Keep a readable version comment next to pinned SHAs when useful for maintenance.
+- Use Ratchet to upgrade workflow refs and regenerate SHA pins through reviewed pull requests.
 - Review the source, ownership, release history, and permissions of new actions.
 - Keep Actions dependencies up to date through reviewed pull requests.
 - Enable Dependabot updates for GitHub Actions dependencies.

diff --git a/...on/docs/methodology/best-practices/ci-cd/github-actions/pinning-with-ratchet.md b/...on/docs/methodology/best-practices/ci-cd/github-actions/pinning-with-ratchet.md
@@ -0,0 +1,125 @@
+---
+sidebar_position: 2
+---
+
+# Pin workflow refs with Ratchet
+
+Use Ratchet to turn human-readable GitHub Actions refs into full commit SHA pins,
+then keep those pins current through reviewed pull requests.
+
+## Why this matters
+
+GitHub Action tags such as `@v4` and branch refs such as `@main` are mutable.
+Production workflows should commit full-length SHAs instead:
+
+```yaml
+- uses: actions/checkout@v4
++ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # ratchet:actions/checkout@v4
+```
+
+That gives you both properties you want:
+
+- a fixed, reviewable revision in the workflow file
+- a machine-managed `# ratchet:` comment that records the version constraint Ratchet should keep tracking
+
+## Recommended workflow
+
+When you copy a methodology snippet into a real repository:
+
+1. Replace documentation placeholders such as `@<version-sha> # x.y.z` with one real released tag.
+2. Run Ratchet across your workflow files.
+3. Commit the rewritten SHA pins.
+
+Example:
+
+```yaml
+uses: actions/checkout@v4
+uses: hoverkraft-tech/ci-github-common/.github/workflows/semantic-pull-request.yml@v0.37.1
+```
+
+For reusable workflow snippets like:
+
+```yaml
+uses: hoverkraft-tech/ci-github-container/.github/workflows/prune-pull-requests-images-tags.yml@<version-sha> # x.y.z
+```
+
+replace the whole placeholder pair with the actual tag first, for example:
+
+```yaml
+uses: hoverkraft-tech/ci-github-common/.github/workflows/linter.yml@0.37.1
+```
+
+From the repository root, run exactly the first time:
+
+```sh
+ratchet pin .github/workflows/*.yml
+```
+
+If Ratchet is not installed locally, run exactly:
+
+```sh
+docker run --rm -v "$PWD:$PWD" -w "$PWD" ghcr.io/sethvargo/ratchet:latest pin .github/workflows/*.yml
+```
+
+That rewrites the workflow to pinned SHAs and adds Ratchet-managed comments such
+as `# ratchet:actions/checkout@v4`.
+
+If you want the final checked-in comment in `# vx.y.z` form instead, start from
+exact tags such as `@v7.0.0` rather than floating tags such as `@v7`, then run
+exactly:
+
+```sh
+find .github/workflows -type f \( -name '*.yml' -o -name '*.yaml' \) -exec perl -0pi -e 's/# ratchet:.*@/# /g' {} +
+```
+
+That rewrites a line such as:
+
+```yaml
+uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # ratchet:actions/checkout@v7.0.0
+```
+
+to:
+
+```yaml
+uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+```
+
+The same reformat also works for reusable workflow refs that use plain semantic
+version tags such as `0.37.1`.
+
+To refresh pins later without changing the tracked version line, run exactly:
+
+```sh
+ratchet update .github/workflows/*.yml
+```
+
+Or with the container image:
+
+```sh
+docker run --rm -v "$PWD:$PWD" -w "$PWD" ghcr.io/sethvargo/ratchet:latest update .github/workflows/*.yml
+```
+
+After either command finishes, review the rewritten `uses:` lines and commit the
+Ratchet-managed form `@<full-sha> # ratchet:<owner>/<repo>@<constraint>`.
+
+If you run the reformat command above, treat it as a readability-only
+post-processing step: the next `ratchet update` will no longer have Ratchet's
+constraint metadata to work from. In that mode, use `ratchet upgrade` when you
+want a future refresh, then rerun the reformat command.
+
+## Which command to use
+
+- Use `ratchet pin` when you start from human-readable refs such as `@v4` and want the first pinned SHA plus a tracked constraint comment.
+- Use `ratchet update` when you want the latest version that still matches the existing Ratchet constraint.
+- Use `ratchet upgrade` only when you intentionally want Ratchet to move to the latest available GitHub Actions version and rewrite the tracked constraint comment.
+- Use the reformat command above only when you explicitly prefer `# vx.y.z` comments over keeping Ratchet metadata in the file.
+
+## Team rule
+
+Do not commit workflow refs as `@main`, `@master`, or floating tags in production
+workflows. Commit the SHA-pinned result that Ratchet generated and keep the
+`# ratchet:` comment if you want future `ratchet update` runs to stay reliable.
+
+## References
+
+- [Ratchet upgrade documentation](https://github.com/sethvargo/ratchet#upgrade)
diff --git a/application/docs/methodology/best-practices/devx/continuous-improvement.md b/application/docs/methodology/best-practices/devx/continuous-improvement.md
@@ -241,6 +241,12 @@ Treat documentation like code:
 
 **Example CI Check:**
 
+:::tip Pin real workflow refs with Ratchet
+This example uses readable tags for clarity. In a real repository, run [Pin
+workflow refs with Ratchet](../ci-cd/github-actions/pinning-with-ratchet.md)
+on your workflow files and commit the rewritten SHA pins.
+:::
+
 ```yaml
 # .github/workflows/docs.yml
 name: Documentation

diff --git a/application/docs/methodology/best-practices/devx/performance-cost-awareness.md b/application/docs/methodology/best-practices/devx/performance-cost-awareness.md
@@ -45,6 +45,12 @@ Set measurable performance targets:
 
 ### CI Performance Checks
 
+:::tip Pin real workflow refs with Ratchet
+This example uses readable tags for clarity. In a real repository, run [Pin
+workflow refs with Ratchet](../ci-cd/github-actions/pinning-with-ratchet.md)
+on your workflow files and commit the rewritten SHA pins.
+:::
+
 ```yaml
 # .github/workflows/performance.yml
 name: Performance

diff --git a/application/docs/methodology/best-practices/devx/security-compliance.md b/application/docs/methodology/best-practices/devx/security-compliance.md
@@ -72,6 +72,13 @@ git secrets --scan-history
 
 Use GitHub secret scanning:
 
+:::tip Pin real workflow refs with Ratchet
+This example uses readable refs for clarity. In a real repository, run [Pin
+workflow refs with Ratchet](../ci-cd/github-actions/pinning-with-ratchet.md)
+on your workflow files and commit the rewritten SHA pins instead of leaving
+floating refs in place.
+:::
+
 ```yaml
 # .github/workflows/security.yml
 name: Security Scan

diff --git a/application/docs/methodology/golden-paths/application/03-ci-cd/github/cd.md b/application/docs/methodology/golden-paths/application/03-ci-cd/github/cd.md
@@ -14,6 +14,14 @@ In the reference application shapes, CD is handled by four workflow entrypoints:
 
 Use [Single application](./single-app.md) for the one-image shape and [Multi-application](./multi-app.md) for the multi-service umbrella-chart shape. This page only describes the shared CD contract.
 
+:::tip Pin copied refs with Ratchet
+These workflow snippets use placeholders such as `@<version-sha>` because the
+exact commit changes over time. In a real repository, replace the placeholder
+with the release tag you want to track, run [Pin workflow refs with
+Ratchet](../../../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md),
+and commit the rewritten SHA pins.
+:::
+
 The contract is the same in both repository shapes:
 
 1. Prepare release metadata continuously.

diff --git a/application/docs/methodology/golden-paths/application/03-ci-cd/github/ci.md b/application/docs/methodology/golden-paths/application/03-ci-cd/github/ci.md
@@ -13,6 +13,18 @@ In the reference application shapes, CI is handled by three workflow entrypoints
 
 Use [Single application](./single-app.md) for the one-image shape and [Multi-application](./multi-app.md) for the multi-service umbrella-chart shape. This page only describes the shared CI contract.
 
+:::tip Pin copied refs with Ratchet
+These workflow snippets use placeholders such as `@<version-sha>` because the
+exact commit changes over time. In a real repository, replace the placeholder
+with the release tag you want to track, run [Pin workflow refs with
+Ratchet](../../../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md),
+and commit the rewritten SHA pins.
+
+For lines shaped like `uses: repo/.github/workflows/file.yml@<version-sha> # x.y.z`,
+replace the whole placeholder ref with a real release tag first, for example
+`@0.37.1` or `@v7.0.0`, before running Ratchet.
+:::
+
 The core pattern is stable across both supported application shapes:
 
 1. Run repository-wide linting first.

diff --git a/application/docs/methodology/golden-paths/application/03-ci-cd/github/index.md b/application/docs/methodology/golden-paths/application/03-ci-cd/github/index.md
@@ -22,7 +22,7 @@ Use another CI/CD platform if you want, but preserve the same contracts:
 - Create a GitHub App for your organization with permissions to read/write contents, deployments, issues, pull requests, and `id-token` usage (for OIDC).
 - Store the GitHub App client ID in variable `CI_BOT_APP_CLIENT_ID` and the private key in secret `CI_BOT_APP_PRIVATE_KEY`.
 - Configure `OCI_REGISTRY` plus environment URLs such as `REVIEW_APPS_URL`, `UAT_URL`, and `PRODUCTION_URL` when you use preview and promoted environments.
-- Pin every reusable workflow and action to a released commit SHA (never `@main`). Use the latest release SHA from the repositories' Releases page or `git ls-remote https://github.com/repo/action.git refs/tags/<version>` and record the exact commit in your workflows, annotating the `uses:` line with the human version (e.g., `@<sha> # v0.30.3`).
+- Pin every reusable workflow and action to a released commit SHA (never `@main`). The snippets in this section keep placeholders such as `@<version-sha>` because exact SHAs change over time. In a real repository, replace those placeholders with the release tag you want to track, run [Pin workflow refs with Ratchet](../../../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md), and commit the rewritten SHA pins.
 
 ## Guides
 

diff --git a/application/docs/methodology/golden-paths/application/03-ci-cd/github/multi-app.md b/application/docs/methodology/golden-paths/application/03-ci-cd/github/multi-app.md
@@ -8,6 +8,14 @@ Use this page when your repository has several deployable services, one Dockerfi
 
 This is the primary GitHub walkthrough for the multi-application shape. Use [GitHub CI](./ci.md) and [GitHub CD](./cd.md) afterward if you want the reusable workflow contracts without the repository-specific details.
 
+:::tip Pin copied refs with Ratchet
+These workflow snippets use placeholders such as `@<version-sha>` because the
+exact commit changes over time. In a real repository, replace the placeholder
+with the release tag you want to track, run [Pin workflow refs with
+Ratchet](../../../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md),
+and commit the rewritten SHA pins.
+:::
+
 ## When this shape fits
 
 - Several deployable services share one repository

diff --git a/...ication/docs/methodology/golden-paths/application/03-ci-cd/github/single-app.md b/...ication/docs/methodology/golden-paths/application/03-ci-cd/github/single-app.md
@@ -8,6 +8,14 @@ Use this page when your repository has one application, one Dockerfile, one runt
 
 This is the primary GitHub walkthrough for the single-application shape. Use [GitHub CI](./ci.md) and [GitHub CD](./cd.md) afterward if you want the reusable workflow contracts without the repository-specific details.
 
+:::tip Pin copied refs with Ratchet
+These workflow snippets use placeholders such as `@<version-sha>` because the
+exact commit changes over time. In a real repository, replace the placeholder
+with the release tag you want to track, run [Pin workflow refs with
+Ratchet](../../../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md),
+and commit the rewritten SHA pins.
+:::
+
 ## When this shape fits
 
 - One deployable service per repository

diff --git a/application/docs/methodology/golden-paths/docker-base-images/03-workflows-setup.md b/application/docs/methodology/golden-paths/docker-base-images/03-workflows-setup.md
@@ -6,6 +6,14 @@ sidebar_position: 4
 
 This page wires the repository to the Hoverkraft reusable workflows using the current production-grade wrapper pattern. The important rule is simple: keep your repository workflows thin, pin released SHAs, and centralize shared CI logic in one internal wrapper.
 
+:::tip Pin copied refs with Ratchet
+These workflow snippets use placeholders such as `@<docker-base-images-sha>` and
+`@<ci-github-common-sha>` because the exact commit changes over time. In a real
+repository, replace the placeholder with the release tag you want to track, run
+[Pin workflow refs with Ratchet](../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md),
+and commit the rewritten SHA pins.
+:::
+
 ## Workflow overview
 
 You'll create these workflow files:
@@ -304,6 +312,8 @@ uses: hoverkraft-tech/ci-github-common/.github/workflows/semantic-pull-request.y
 ```
 
 Do not leave `@main` in documentation examples or production workflows.
+Use [Pin workflow refs with Ratchet](../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md)
+to turn version tags into reviewed SHA pins.
 
 ## Workflow Summary
 

diff --git a/...ation/docs/methodology/golden-paths/docker-base-images/04-release-publishing.md b/...ation/docs/methodology/golden-paths/docker-base-images/04-release-publishing.md
@@ -6,6 +6,14 @@ sidebar_position: 5
 
 The current release model is image-centric, not repository-centric. You prepare release pull requests for image directories, then manually dispatch the release workflow to create and publish releases only for images that changed.
 
+:::tip Pin copied refs with Ratchet
+These workflow snippets use placeholders such as `@<docker-base-images-sha>`
+because the exact commit changes over time. In a real repository, replace the
+placeholder with the release tag you want to track, run [Pin workflow refs with
+Ratchet](../../best-practices/ci-cd/github-actions/pinning-with-ratchet.md), and
+commit the rewritten SHA pins.
+:::
+
 ## Release workflow overview
 
 The release process follows this flow:

diff --git a/...cs/projects/ci-cd-tools/docker-base-images/actions/should-build-images/index.md b/...cs/projects/ci-cd-tools/docker-base-images/actions/should-build-images/index.md
@@ -58,11 +58,11 @@ Check if some files have changed requiring the build of the given images.
 
 ## Inputs
 
-| **Input**      | **Description**                                                                                                   | **Required** | **Default** |
-| -------------- | ----------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |
-| **`images`**   | Image names located in the 'images' folder.                                                                       | **true**     | -           |
-|                | Formatted as a JSON array.                                                                                        |              |             |
-|                | Example: `["php-8", "nodejs-24"]`                                                                                 |              |             |
+| **Input**      | **Description**                                                                                                                                                | **Required** | **Default** |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------- |
+| **`images`**   | Image names located in the 'images' folder.                                                                                                                    | **true**     | -           |
+|                | Formatted as a JSON array.                                                                                                                                     |              |             |
+|                | Example: `["php-8", "nodejs-24"]`                                                                                                                              |              |             |
 | **`base-sha`** | Specify a different base commit SHA used for comparing changes. See [https://github.com/tj-actions/changed-files](https://github.com/tj-actions/changed-files) | **false**    | -           |
 
 <!-- inputs:end -->