feat(ci-cd): add GitHub actions pinning process

Signed-off-by: Emilien Escalle <emilien.escalle@escemi.com>

Author: neilime

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

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.

application/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)

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

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

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

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.

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.

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
 

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