Skip to content

docs(security): Rejustify internal reusable workflow SHA-pin exemption as risk acceptance - #101

Merged
yunseo-kim merged 5 commits into
mainfrom
docs/reusable-workflow-sha-pin-exemption
Oct 26, 2026
Merged

yunseo-kim merged 5 commits into
mainfrom
docs/reusable-workflow-sha-pin-exemption

Conversation

@yunseo-kim

@yunseo-kim yunseo-kim commented Oct 26, 2026 •

Copy link
Copy Markdown
Member

Summary

Replaces the factually incorrect rationale for the internal reusable workflow SHA-pin exemption ("Dependabot cannot propose updates") with a threat-model-accurate one, and fixes documentation contradictions around it.

  • What changed?
    • docs/security/workflow-hardening.md: the exemption note is now an Internal Reusable Workflows subsection separating the two cases. Local ./ references are structurally immutable (resolved at the caller's commit); cross-repo @main references are a deliberate risk acceptance, not a security equivalent of SHA pinning. High-privilege consumers may pin a full-length SHA.
    • README.md: the reusable-workflow note now states the risk-acceptance rationale; consumer examples use @main (they previously showed @<pin-sha> while the note allowed @main); the "Always pin" rollout note is aligned with the policy.
    • docs/security/dependency-security.md: the consumer caller example uses @main with a link to the exemption policy.
    • AGENTS.md: regenerated for the current repo state; SHA-pinning, consumer-exception, and anti-pattern entries aligned with the rejustified exemption.
    • profile/README.md: new organization profile; MD026 exception scoped to the H1 because "Inc." is an abbreviation, not trailing punctuation.
  • Why is this needed? Dependabot can update SHA-pinned action references (including untagged SHAs via branch-HEAD tracking), so the old rationale did not hold. The exemption is kept, but now rests on the defensible grounds: structural immutability for local paths, and an explicit, documented trust-boundary risk acceptance for @main.

Related Issues

  • None

Change Type

  • Documentation

Changelog

  • Category: None
  • User-facing note: Internal policy documentation only; no consumer-facing behavior change.

Changelog update:

  • Not needed because this change is not user-facing

Checklist

General

  • PR title follows Conventional Commits format:
    type(scope): Summary
  • This PR does not expose backend/internal implementation details in a public repo.
  • No secrets, tokens, keys, or private endpoints are included.
  • Changes stay within this repository's intended scope.

CI/Workflow Changes (if applicable)

Not applicable: no workflow or CI/CD configuration changes.

Protocol / Compatibility Impact

  • No protocol/spec impact

Testing

  • Lint and format pass
  • Manual verification performed

Describe test evidence: bun run lint:md reports 0 issues across all 19 Markdown files (including the MD026-scoped profile heading); bun run format:check reports all files formatted; residual scan confirms no remaining @<pin-sha> placeholders or the old Dependabot rationale. Local cubic review ran before commit; the one remaining P2 (base64 badge SVG) is a disputed style preference on the standard shields.io custom-logo mechanism.

Documentation

  • README updated
  • Spec/docs updated
  • Changelog decision completed above

Rollout / Risk

  • Risk level: Low
  • Rollback plan: Revert the three commits on this branch; no behavioral or CI impact.

Reviewer Checklist

  • Scope is clear and minimal
  • Security and boundary checks passed
  • Tests and docs are sufficient
  • Compatibility impact is correctly handled

…n as risk acceptance

Replace the factually incorrect Dependabot-support rationale with the two
distinct cases: local ./ references are structurally immutable (resolved at
the caller's commit), and cross-repo @main references are a deliberate risk
acceptance for immediate fleet-wide propagation, not a security equivalent
of SHA pinning. High-privilege consumers may pin a full-length SHA. Fix the
README contradiction where consumer examples used @<pin-sha> while the note
allowed @main.

Signed-off-by: Yunseo Kim <git@yunseo.kim>
…mption rationale

Regenerate the agent guide to cover the org profile, security companion
docs, caller/reusable workflow pairs, Lefthook, and the lint/format stack.
Align the SHA-pinning, consumer-exception, and anti-pattern entries with
the rejustified internal reusable workflow exemption.

Signed-off-by: Yunseo Kim <git@yunseo.kim>
Add the public org profile with the Windlass description, project table,
and community links. Scope an MD026 exception to the H1 since "Inc." is an
abbreviation, not trailing punctuation.

Signed-off-by: Yunseo Kim <git@yunseo.kim>

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread docs/security/workflow-hardening.md Outdated
Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
…ss trust boundary

The branch-name risk acceptance only holds for callers inside the
organization. External callers of these public reusable workflows are
outside the trust boundary and must pin a full-length commit SHA.

Signed-off-by: Yunseo Kim <git@yunseo.kim>
… AGENTS.md

Update the generation header to commit 381aac4, describe the repo's actual
documentation and configuration formats (Markdown, YAML, JSON/JSONC, TOML,
EditorConfig), and replace the overstated disabled-rule ranges with the
exact list from .markdownlint-cli2.jsonc (MD011, MD021, and MD036 remain
enabled). Also scope the consumer exception to Windlass callers.

Signed-off-by: Yunseo Kim <git@yunseo.kim>
@yunseo-kim
yunseo-kim merged commit 557e765 into main Oct 26, 2026
13 checks passed
@yunseo-kim
yunseo-kim deleted the docs/reusable-workflow-sha-pin-exemption branch October 26, 2026 17:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant