admin install should pin reusable workflows and actions to a commit SHA instead of v0

[rh-hemartin]

What happens:

When fullsend admin install scaffolds caller workflows into a repo, all uses: references to fullsend reusable workflows and shared actions are pinned to the floating v0 tag:

uses: fullsend-ai/fullsend/.github/workflows/reusable-triage.yml@v0
uses: fullsend-ai/fullsend/.github/actions/mint-token@v0

This applies to reusable-triage.yml, reusable-code.yml, reusable-review.yml, reusable-fix.yml, reusable-retro.yml, mint-token, setup-gcp, and validate-enrollment.

What should happen:

The scaffolded uses: lines should be pinned to the commit SHA of the fullsend release used to run the install, with the semver version in a comment:

uses: fullsend-ai/fullsend/.github/workflows/reusable-triage.yml@abc1234  # v1.2.3
uses: fullsend-ai/fullsend/.github/actions/mint-token@abc1234  # v1.2.3

When installing from a development build (binary built from main rather than a release tag), the scaffolded references should pin to the HEAD SHA of main at build time, with a comment identifying it as a dev build:

uses: fullsend-ai/fullsend/.github/workflows/reusable-triage.yml@abc1234  # main (dev)
uses: fullsend-ai/fullsend/.github/actions/mint-token@abc1234  # main (dev)

This allows contributors to install from a local main build and have the scaffolded workflows actually exercise the in-progress workflow changes, rather than whatever v0 points to.

Context:

SHA pinning is a supply-chain security best practice. A floating tag like v0 can be moved to a different commit, silently changing what runs in installed repos without any indication in the caller workflow files. Pinning to the SHA of the installed version makes the ref immutable and auditable.

The dev-build case (see also #1166) is equally important for testability: without it, testing workflow changes end-to-end requires either moving the v0 tag manually or accepting that the installed workflows are running stale code.

[fullsend-ai-triage]

Triage Summary

This is a supply-chain security improvement to replace floating @v0 tag references in scaffolded workflows with immutable SHA-pinned references.

Problem

All uses: references to fullsend reusable workflows and composite actions are hardcoded to @v0 in the scaffold templates. A floating tag is mutable and can be moved without any indication in the caller workflow files.

Affected Components

• Templates: internal/scaffold/fullsend-repo/.github/workflows/*.yml
• Install logic: internal/layers/workflows.go (WorkflowsLayer.Install())
• Build system: Needs to embed commit SHA and version at build time

Recommended Approach

1. Replace @v0 in scaffold templates with a substitution placeholder
2. Embed the build commit SHA and version tag into the binary via ldflags
3. Substitute the placeholder during install with @<SHA> # <version>
4. Handle the dev-build case: use HEAD SHA with # main (dev) comment
5. Update scaffold tests to validate SHA-pinned output

Proposed Test Case

Scenario: Scaffolded workflows use SHA-pinned references
  Given the CLI is built from commit abc1234 at version v1.2.3
  When fullsend admin install scaffolds workflows into a target repo
  Then every uses: line referencing fullsend-ai/fullsend/ ends with @<40-char-hex-SHA>
  And each pinned line has a trailing comment with the version (# v1.2.3)
  And dev builds use the HEAD SHA with comment # main (dev)
  And re-running install with a newer version updates the SHA and comment

Severity

Medium — security best practice improvement. Exploitation requires write access to the fullsend repo to move the v0 tag, but SHA pinning eliminates this attack vector entirely.

Previous run

Triage Summary

This is a well-defined supply-chain security improvement. The scaffolded caller workflows and composite action references are currently hardcoded to the floating @v0 tag, with no dynamic version substitution during install.

Affected Code

• Templates: internal/scaffold/fullsend-repo/.github/workflows/*.yml — all stage caller workflows (triage, code, review, fix, retro, dispatch) plus the per-repo shim template
• Install logic: internal/layers/workflows.go (WorkflowsLayer.Install()) copies templates verbatim via scaffold.WalkFullsendRepo()
• CLI entry point: internal/cli/admin.go (runInstall() and runPerRepoInstall())
• Tests: internal/scaffold/scaffold_test.go asserts @v0 presence on ~10 references

Recommended Approach

1. Introduce a template placeholder (e.g., @__FULLSEND_REF__) in scaffold YAML files
2. Embed the build commit SHA into the CLI binary at build time
3. Substitute the placeholder with the SHA during WorkflowsLayer.Install(), appending the semver tag as a comment
4. Update all scaffold tests to validate SHA-pinned output

Proposed Test Case

Scenario: Scaffolded workflows use SHA-pinned references
  Given the CLI is built from commit abc1234 at version v1.2.3
  When fullsend admin install runs against a target repo
  Then every `uses:` line referencing fullsend-ai/fullsend/ ends with @<40-char-hex-SHA>
  And each pinned line has a trailing comment with the semver version (e.g., # v1.2.3)
  And both per-org and per-repo install modes produce pinned references
  And re-running install with a newer version updates the SHA

Severity

Medium — security best practice improvement; the current floating tag is a known supply-chain risk pattern but requires write access to the fullsend repo to exploit.

---

Labels: This is a security-related feature request affecting the install component. Marking as ready-to-code since the problem and solution are well-understood.

[ifireball]

/fs-prioritize

[fullsend-ai-triage]

Meeting update — 2026-05-27

Relevant to this issue: Discussion included instructing users to pin their fullsend versions to v0.10 or v0.11, reinforcing the need for a consistent version pinning strategy in scaffolded workflows.

• Users should pin to specific minor versions rather than floating tags
• This was raised in the context of simplifying installation and reducing breakage for new adopters

Related PRs: In progress: #1278 (fullsend_ai_ref for self-consistent version pinning)

Next steps: Finalize version pinning approach and document recommended pin targets.

Meeting notes

[fullsend-ai-prioritize]

RICE Priority Score: 1.07

Score breakdown

Dimension	Score	Reasoning
Reach	2	All users who run fullsend admin install are affected, as every scaffolded repo gets floating @v0 references. Meeting notes confirm this is being discussed as a general user-facing concern, with users being instructed to pin versions. Score: 2 (most active users across orgs).
Impact	1	This is a supply-chain security best practice improvement. The current floating tag is exploitable only with write access to the fullsend repo, and users can manually pin SHAs as a workaround. The dev-build testability improvement is a secondary benefit. Triage rates severity as Medium. Score: 1 (noticeable improvement to workflow).
Confidence	0.8	The issue is very well-described with clear affected components, a detailed triage summary, proposed implementation steps, and a related PR (#1278) already in progress. The scope and approach are well-understood. Score: 0.8 (high confidence).
Effort	1.5	Requires changes across scaffold templates, install logic (WorkflowsLayer), build system (ldflags for SHA/version embedding), and test updates. The triage outlines 4-5 distinct steps touching multiple components. A related PR is in progress which may reduce remaining effort. Score: 1.5 (moderate — multiple components and build system work).

Formula: (2 x 1 x 0.8) / 1.5 = 1.07