docs: team best-practice guide for pinning GitHub Actions (#146) by dkastl · Pull Request #53 · geolonia/.github

dkastl · 2026-06-09T01:59:48Z

Closes the documentation sub-issue of the Actions pinning standard (geolonia-operations#146, epic geolonia-operations#142).

Adds docs/github-actions-pinning.md — a developer-facing guide covering:

Why we pin to a commit SHA (mutable tags vs immutable SHA, the supply-chain risk in plain terms, with the tj-actions/changed-files example).
How the pieces fit — pinact (pins + verifies) + Dependabot (maintains + cooldown) + .pinact.yml (min-age), the one "nothing younger than 7 days" rule shared with pnpm, and why Dependabot cooldown is 8 while pinact min_age is 7.
Adding/changing an action — never hand-edit SHAs; let the pre-commit hook / pinact run do it.
Handling a Dependabot PR and a failing Action Pinning Check (table of causes + fixes).
FAQ — missed updates, version comments, first-party pinning, persist-credentials on checkout v6+, adopting in a new repo.

It cross-links the Action Pinning Check reusable-workflow reference rather than duplicating it. Also added to the mkdocs nav and the index Related pages.

Summary by CodeRabbit

Documentation
- Added a comprehensive "GitHub Actions Pinning" guide covering rationale, enforcement, adoption steps, operational rules, remediation, and links to related resources; added the guide to site navigation and related pages.
Chores
- Added a canonical Dependabot configuration for action pinning and updated workflow docs to reference copying it into repositories and required workflow checks.

Developer-facing 'why and how' guide for the org Actions pinning standard: why SHA-pin (supply chain), how pinact + Dependabot + .pinact.yml fit (the 7-day rule, and why Dependabot cooldown is 8), how to add/bump an action, how to handle a Dependabot PR and a failing Action Pinning Check, and an FAQ (incl. persist-credentials on checkout v6+). Cross-links the reusable-workflow reference instead of duplicating. Added to the mkdocs nav and the index Related pages.

coderabbitai · 2026-06-09T01:59:58Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ae49c362-7acb-4a9b-949d-6b0f01783e0b

📥 Commits

Reviewing files that changed from the base of the PR and between 9a8a206 and ca44f85.

📒 Files selected for processing (1)

docs/github-actions-pinning.md

Walkthrough

Adds a new “GitHub Actions Pinning” guide documenting SHA-based action pinning, security rationale, pinact/Dependabot coordination (including an 8-day cooldown), adoption steps, operational rules, and integrates the page into site navigation and index.

Changes

GitHub Actions Pinning Guide

Layer / File(s)	Summary
Overview and security rationale `docs/github-actions-pinning.md`	Introduces the pinning standard, shows the 40-char commit-SHA + version comment example, and links to the reusable Action Pinning Check docs.
Tooling and Dependabot config `docs/github-actions-pinning.md`, `pinact/dependabot.yml`	Describes coordination between `pinact`, Dependabot, and `.pinact.yml` including the “nothing younger than 7 days” rule, and adds canonical `pinact/dependabot.yml` with weekly schedule and 8-day cooldown.
Adoption steps and required workflows `docs/github-actions-pinning.md`, `docs/workflows.md`	Explains onboarding: copy canonical `pinact/*` configs (optional pre-commit), add the reusable Action Pinning Check workflow, and run `pinact run`; updates workflows docs to require copying `pinact/dependabot.yml`.
Day-to-day operations and references `docs/github-actions-pinning.md`	Lists operational rules (never hand-edit SHAs), Dependabot weekly PR behavior, and "See also" links to the reusable workflow, canonical configs, and upstream `pinact` docs.
Site integration `docs/index.md`, `mkdocs.yml`	Adds the new page to the docs index and mkdocs navigation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

geolonia/geolonia-operations#142: Implements the org-wide SHA-based Actions pinning policy documented in this PR.
geolonia/geolonia-operations#144: Matches the per-repo adoption steps (copy configs, run pinact) described by this PR.
geolonia/geolonia-operations#146: Requests a pinning best-practice guide that this PR supplies.

Possibly related PRs

geolonia/.github#48: Complements the reusable Action Pinning Check workflow referenced by this guide.
geolonia/.github#50: Aligns Dependabot cooldown guidance (8 days) with pinact expectations.
geolonia/.github#51: Provides the canonical Dependabot pinning config that this PR adds.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a best-practice guide document for pinning GitHub Actions, which aligns with all modified files.
Description check	✅ Passed	The description provides comprehensive context including the issue reference, detailed summary of the added documentation, cross-linking approach, and specific topics covered. It goes well beyond the template requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/actions-pinning-guide

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-06-09T02:00:01Z

Secret Leak Check

OK No secrets detected in this PR's diff.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/github-actions-pinning.md`:
- Around line 138-139: Update the incorrect canonical path reference
"pinact/.pinact.yml" in the docs text to the correct root path ".pinact.yml" so
it matches the documented source of truth and Line 129; specifically change the
string "pinact/.pinact.yml" (seen in the diff) to ".pinact.yml" and keep
"pinact/.pre-commit-config.example.yaml" as-is.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: e5f6adc0-115e-49de-8e9c-2ebae24bdba5

📥 Commits

Reviewing files that changed from the base of the PR and between f217e1e and 18ee338.

📒 Files selected for processing (3)

docs/github-actions-pinning.md
docs/index.md
mkdocs.yml

Make the adoption FAQ consistent with workflows.md and the See-also: the canonical file to copy is this repo's pinact/.pinact.yml, copied to the consuming repo root as .pinact.yml. (Root .pinact.yml in this repo is geolonia/.github's own active config, not the template.)

github-actions · 2026-06-09T02:07:25Z

Secret Leak Check

OK No secrets detected in this PR's diff.

…methods Review feedback: - Drop the FAQ and 'When the Action Pinning Check fails' sections and cut within-page repetition (guide is ~83 lines now, down from ~145). The essential 'never hand-edit a SHA; run pinact run' tip is folded into Day to day. - Add pinact/dependabot.yml as the canonical Dependabot template so the pinact/ directory holds all three copyable files; point the guide and workflows.md Required files at it. - Document both ways to add the Action Pinning Check workflow: the GitHub Actions 'New workflow -> By Geolonia' picker, or copying the file. - Point clearly at this repo's pinact/ directory (linked).

github-actions · 2026-06-09T02:13:04Z

Secret Leak Check

OK No secrets detected in this PR's diff.

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/github-actions-pinning.md`:
- Line 42: Replace the unhyphenated phrase "168 hour floor" with the compound
adjective "168-hour floor" in the docs text (search for the exact string "168
hour floor"); ensure the hyphenated form is used where it modifies "floor" so
the phrase reads "168-hour floor".
- Around line 19-21: Update the incorrect incident date and wording for the
`tj-actions/changed-files` compromise: replace "2026" with "March 2025" and add
that the supply-chain/tag attack occurred in March 2025 (with retroactive tag
changes) and was mitigated by March 15, 2025; optionally append the advisory
identifier (GHSA-mw4p-6x4p-x5m5) for clarity where `tj-actions/changed-files` is
mentioned in the paragraph.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 89d4e9ff-1ecb-4b82-8b70-45a753b00f55

📥 Commits

Reviewing files that changed from the base of the PR and between d03da16 and 9a8a206.

📒 Files selected for processing (3)

docs/github-actions-pinning.md
docs/workflows.md
pinact/dependabot.yml

Review feedback: drop the tj-actions example (and its date) and just state in plain words what pinning to a SHA prevents (a moved or hijacked tag silently swapping in different code on a run that can read secrets). Hyphenate '168-hour'.

github-actions · 2026-06-09T02:51:06Z

Secret Leak Check

OK No secrets detected in this PR's diff.

coderabbitai Bot reviewed Jun 9, 2026

View reviewed changes

Comment thread docs/github-actions-pinning.md Outdated

coderabbitai Bot reviewed Jun 9, 2026

View reviewed changes

Comment thread docs/github-actions-pinning.md Outdated

Comment thread docs/github-actions-pinning.md Outdated

dkastl merged commit 9e5b10e into main Jun 9, 2026
3 checks passed

dkastl deleted the docs/actions-pinning-guide branch June 9, 2026 03:08

coderabbitai Bot mentioned this pull request Jun 17, 2026

fix: Hera budget dubbelräkning + adjust-fixed-price samma-månad/icke-fp luisbotero6-code/bytraq#371

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: team best-practice guide for pinning GitHub Actions (#146)#53

docs: team best-practice guide for pinning GitHub Actions (#146)#53
dkastl merged 4 commits into
mainfrom
docs/actions-pinning-guide

dkastl commented Jun 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

dkastl commented Jun 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Uh oh!

github-actions Bot commented Jun 9, 2026

Secret Leak Check

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 9, 2026

Secret Leak Check

Uh oh!

github-actions Bot commented Jun 9, 2026

Secret Leak Check

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 9, 2026

Secret Leak Check

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dkastl commented Jun 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 9, 2026 •

edited

Loading