Pin GitHub Actions to commit SHAs repo-wide

[bobtista]

Problem

GitHub Actions are referenced by tag rather than by commit SHA. A tag is mutable, so a compromised or retagged action changes what CI executes without any change in this repository.

Proposed approach

Adopt a repo-wide policy of pinning actions to full commit SHAs, with a comment recording the human-readable version alongside each pin.

Acceptance criteria

• Actions across all workflows are pinned to full commit SHAs.
• Each pin carries a comment naming the version it corresponds to.
• A documented process exists for updating pins.

Notes

Raised in the review thread on #313. Low priority — recorded so it is not lost, not intended to block Alpha 5.

[coderabbitai]

Coding Plan

Summary

• Convert all ~25 uses: references across ci.yml, deploy.yml, and release.yml from mutable version tags to immutable full commit SHAs, each annotated with a version comment, keeping duplicated actions consistent.
• Add a .github/dependabot.yml github-actions entry so pins and their version comments are maintained automatically with minimal ongoing effort.
• Add a concise docs/dev/ page (linked from the dev index and referenced from CONTRIBUTING.md) documenting the pinning policy and both automated and manual update processes.

Design Choices

Design Choice 1: How should the "documented process for updating pins" be satisfied?

Options Considered:

1. Manual-only: add a docs page describing how to look up SHAs and update comments by hand.
2. Dependabot + docs: add a github-actions Dependabot config (which natively supports SHA-pinned actions and auto-updates the inline version comment) and a short docs page explaining both the automated flow and manual fallback.
3. External CLI tool (e.g., pin-github-action) documented as the required workflow.

Chosen Option: 2

Rationale: Dependabot natively keeps SHA pins and their version comments current with minimal maintenance and aligns with GitHub's official supply-chain guidance, while the docs page covers manual updates for reviewers; a mandatory external CLI adds friction inappropriate for a low-priority change.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Pin all workflow actions to commit SHAs

This phase delivers the core acceptance criteria: converting every mutable tag reference into an immutable full-length commit SHA and annotating each with a version comment. The goal is that CI executes exactly the reviewed code regardless of upstream retagging, with human-readable version context preserved at each call site.

Task 1: Resolve each action's tag to its full commit SHA

Establish the authoritative SHA for every unique action/version pair before editing workflows, ensuring consistency across duplicated references.

• For each of the 9 unique actions, resolve the current tag (@v4, @v3, @v2) to the full-length commit SHA of that release, verified against the action's upstream repository (not a fork).
• Record the resolved SHA alongside its exact release version string (e.g., v4.2.2) so the same SHA/comment pair is applied uniformly wherever the action appears.
• Confirm actions duplicated across files (e.g., actions/cache, actions/upload-artifact, actions/checkout, actions/setup-dotnet) map to a single agreed SHA to avoid drift between ci.yml and release.yml.

Task 2: Update `.github/workflows/ci.yml`

Pin all action references in the CI workflow.

• Replace every uses: owner/repo@vX with uses: owner/repo@<full-sha> for actions/checkout, dorny/paths-filter, actions/setup-dotnet, actions/cache, and all five actions/upload-artifact steps.
• Append an inline comment naming the version to each pin (e.g., # v4.2.2).
• Leave env:, concurrency, permissions, and job structure untouched.

Task 3: Update `.github/workflows/deploy.yml`

Pin all action references in the deploy workflow.

• Replace tag refs with SHAs plus version comments for actions/checkout, pnpm/action-setup, and actions/setup-node.
• Preserve the pages concurrency group and all other configuration.

Task 4: Update `.github/workflows/release.yml`

Pin all action references in the release workflow.

• Replace tag refs with SHAs plus version comments for actions/checkout, actions/setup-dotnet, actions/cache, actions/upload-artifact, actions/download-artifact, and softprops/action-gh-release.
• Ensure actions/cache, actions/checkout, actions/setup-dotnet, and actions/upload-artifact use the identical SHAs chosen in Task 1.1 so they match ci.yml.

🤖 Prompt for AI agents

Implement full-length commit SHA pinning for all GitHub Actions references
across the three workflow files, with inline version comments, so CI executes
exactly the reviewed code regardless of upstream retagging.

- First, for each of the 9 unique actions used in the repo (`actions/checkout`,
`dorny/paths-filter`, `actions/setup-dotnet`, `actions/cache`,
`actions/upload-artifact`, `pnpm/action-setup`, `actions/setup-node`,
`actions/download-artifact`, `softprops/action-gh-release`), resolve the
currently referenced tag (`@v4`, `@v3`, `@v2`) to the full-length commit SHA of
that release, verifying against the action's upstream repository (not a fork).
Record each resolved SHA alongside its exact release version string (e.g.,
`v4.2.2`) so the same SHA/comment pair can be applied uniformly everywhere that
action appears.
- Ensure actions duplicated across files (`actions/cache`,
`actions/upload-artifact`, `actions/checkout`, `actions/setup-dotnet`) map to a
single agreed SHA to avoid drift between `ci.yml` and `release.yml`.
- In `.github/workflows/ci.yml`, replace every `uses: owner/repo@vX` with `uses:
owner/repo@<full-sha>` for `actions/checkout`, `dorny/paths-filter`,
`actions/setup-dotnet`, `actions/cache`, and all five `actions/upload-artifact`
steps, appending an inline comment naming the version (e.g., `# v4.2.2`) to each
pin. Leave `env:`, `concurrency`, `permissions`, and job structure untouched.
- In `.github/workflows/deploy.yml`, replace tag refs with SHAs plus version
comments for `actions/checkout`, `pnpm/action-setup`, and `actions/setup-node`,
preserving the `pages` concurrency group and all other configuration.
- In `.github/workflows/release.yml`, replace tag refs with SHAs plus version
comments for `actions/checkout`, `actions/setup-dotnet`, `actions/cache`,
`actions/upload-artifact`, `actions/download-artifact`, and
`softprops/action-gh-release`, ensuring `actions/cache`, `actions/checkout`,
`actions/setup-dotnet`, and `actions/upload-artifact` use the identical SHAs
chosen above so they match `ci.yml`.

Phase 2: Establish a documented, low-maintenance update process

This phase satisfies the "documented process for updating pins" criterion by adding automation that natively maintains SHA pins and their version comments, plus concise contributor-facing documentation describing both the automated flow and the manual procedure.

Task 1: Add Dependabot configuration for the github-actions ecosystem

Introduce automation that opens PRs to bump pinned SHAs and keeps the inline version comments current.

• Create .github/dependabot.yml with a package-ecosystem: "github-actions" entry, directory: "/", and a reasonable update schedule.
• Rely on Dependabot's native support for SHA-pinned actions, which updates both the SHA and the trailing # vX.Y.Z comment together.

Task 2: Document the SHA-pinning policy and update process

Provide a single-topic developer doc explaining the policy and how to update pins manually or via Dependabot.

• Create a new page under docs/dev/ (e.g., docs/dev/ci-dependency-pinning.md) mirroring the style of existing topic docs like docs/dev/constants.md.
• Describe the policy (all actions pinned to full commit SHAs with a version comment), the automated update path via Dependabot, and the manual procedure for resolving a tag to a verified upstream SHA when needed.
• Link the new page from docs/dev/index.md and add a brief pointer in CONTRIBUTING.md so contributors editing workflows find the process.

🤖 Prompt for AI agents

Add automation and documentation so the SHA-pinning policy from Phase 1 is easy
to maintain going forward.

- Create `.github/dependabot.yml` with a `package-ecosystem: "github-actions"`
entry, `directory: "/"`, and a reasonable update schedule, relying on
Dependabot's native support for SHA-pinned actions to update both the SHA and
the trailing `# vX.Y.Z` comment together.
- Create a new single-topic developer doc under `docs/dev/` (e.g.,
`docs/dev/ci-dependency-pinning.md`), mirroring the style of existing topic docs
like `docs/dev/constants.md`. In it, describe the policy (all actions pinned to
full commit SHAs with a version comment), the automated update path via
Dependabot, and the manual procedure for resolving a tag to a verified upstream
SHA when needed.
- Link the new page from `docs/dev/index.md` and add a brief pointer in
`CONTRIBUTING.md` so contributors editing workflows can find the process.

Research

The repository uses three GitHub Actions workflows under .github/workflows/ — ci.yml, deploy.yml, and release.yml. Across them there are 9 unique third-party/GitHub-hosted actions (actions/checkout, dorny/paths-filter, actions/setup-dotnet, actions/cache, actions/upload-artifact, pnpm/action-setup, actions/setup-node, actions/download-artifact, softprops/action-gh-release) referenced across ~25 uses: steps, all currently pinned to mutable major-version tags (@v4, @v3, @v2).

There are no local/composite actions, no matrix strategies, and no Dependabot/Renovate configuration.

Developer documentation lives under docs/dev/, following a one-topic-per-file convention indexed by docs/dev/index.md; CONTRIBUTING.md mentions CI only in passing.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement full-length commit SHA pinning for all GitHub Actions references
across the three workflow files, with inline version comments, so CI executes
exactly the reviewed code regardless of upstream retagging.

- First, for each of the 9 unique actions used in the repo (`actions/checkout`,
`dorny/paths-filter`, `actions/setup-dotnet`, `actions/cache`,
`actions/upload-artifact`, `pnpm/action-setup`, `actions/setup-node`,
`actions/download-artifact`, `softprops/action-gh-release`), resolve the
currently referenced tag (`@v4`, `@v3`, `@v2`) to the full-length commit SHA of
that release, verifying against the action's upstream repository (not a fork).
Record each resolved SHA alongside its exact release version string (e.g.,
`v4.2.2`) so the same SHA/comment pair can be applied uniformly everywhere that
action appears.
- Ensure actions duplicated across files (`actions/cache`,
`actions/upload-artifact`, `actions/checkout`, `actions/setup-dotnet`) map to a
single agreed SHA to avoid drift between `ci.yml` and `release.yml`.
- In `.github/workflows/ci.yml`, replace every `uses: owner/repo@vX` with `uses:
owner/repo@<full-sha>` for `actions/checkout`, `dorny/paths-filter`,
`actions/setup-dotnet`, `actions/cache`, and all five `actions/upload-artifact`
steps, appending an inline comment naming the version (e.g., `# v4.2.2`) to each
pin. Leave `env:`, `concurrency`, `permissions`, and job structure untouched.
- In `.github/workflows/deploy.yml`, replace tag refs with SHAs plus version
comments for `actions/checkout`, `pnpm/action-setup`, and `actions/setup-node`,
preserving the `pages` concurrency group and all other configuration.
- In `.github/workflows/release.yml`, replace tag refs with SHAs plus version
comments for `actions/checkout`, `actions/setup-dotnet`, `actions/cache`,
`actions/upload-artifact`, `actions/download-artifact`, and
`softprops/action-gh-release`, ensuring `actions/cache`, `actions/checkout`,
`actions/setup-dotnet`, and `actions/upload-artifact` use the identical SHAs
chosen above so they match `ci.yml`.
===============================================================================

Task: 2

Add automation and documentation so the SHA-pinning policy from Phase 1 is easy
to maintain going forward.

- Create `.github/dependabot.yml` with a `package-ecosystem: "github-actions"`
entry, `directory: "/"`, and a reasonable update schedule, relying on
Dependabot's native support for SHA-pinned actions to update both the SHA and
the trailing `# vX.Y.Z` comment together.
- Create a new single-topic developer doc under `docs/dev/` (e.g.,
`docs/dev/ci-dependency-pinning.md`), mirroring the style of existing topic docs
like `docs/dev/constants.md`. In it, describe the policy (all actions pinned to
full commit SHAs with a version comment), the automated update path via
Dependabot, and the manual procedure for resolving a tag to a verified upstream
SHA when needed.
- Link the new page from `docs/dev/index.md` and add a brief pointer in
`CONTRIBUTING.md` so contributors editing workflows can find the process.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!