workflowfile: guard local action migration when checkout uses a custom ref

[kuma0128]

Problem

Migrating ./local-action to $/local-action changes which code runs when a preceding actions/checkout step selects a different ref. The local path reads the checked-out workspace, while $/ resolves at the running commit.

This also affects nested references: a workflow can check out a custom ref and call an existing $/outer whose definition still uses ./inner. A file-local check misses that migration.

Fix

Reject the migration before writing any files when a preceding checkout has a non-empty ref other than ${{ github.sha }}. The error identifies the action being migrated and the checkout's ref, file, and line, and points to --no-migrate-local-actions to preserve local references.

• Follow checkout state through nested ./… and $/… composite calls and back to subsequent caller steps. Keep jobs independent.
• Check all workflow callers before changing shared composite definitions, including callers outside a scoped run. Only references in files being migrated can trigger the checkout-ref rejection.
• Keep earlier custom refs blocking even if a later checkout resets the workspace, since that later step may be conditional.
• Reuse the existing YAML and repository-boundary helpers. Cache traversal results by checkout context, reject composite cycles, and document the guard in the README.

The guard covers explicit checkout steps in workflows and in-repo composite actions; it does not analyze workspace changes through scripts or remote actions. Workflows retaining ./… references still cannot be onboarded to the lockfile.

Fixes #112.

Tests

• Confirmed both the direct checkout-ref and cross-file regression tests fail before their fixes.
• Unit tests cover ref classification, ordering, job boundaries, nested and repeated composite calls, conditional calls, YAML aliases, symlinks, scoped validation, and cycles. Command tests verify that rejection leaves workflows, action definitions, and the lockfile untouched, without resolving dependencies, in terminal, JSON, and scoped runs.
• make test (including the race-enabled Go suite), make build fmt-check vet, and all 34 make test-stub scenarios passed.
• Compiled-CLI smoke tests for custom-ref checkout → $/outer → ./inner exited 2, reported the checkout source, and left every file unchanged in both full and scoped runs.

[Copilot]

🟡 Changes recommended

The guard misses alternate-repository checkouts and checkout context inherited by migrated composite actions.

1 open finding

• Checkout context is not propagated into composite action migrations · New

What changed in this PR

Adds safeguards to prevent unsafe ./… to $/… migrations after custom-ref checkouts.

Changes:

• Detects preceding custom-ref checkout steps.
• Preserves all-or-nothing migration behavior.
• Adds unit, command, alias, and documentation coverage.

File	Description
README.md	Documents migration restrictions.
internal/​workflowfile/​workflowfile_test.go	Tests ref classification.
internal/​workflowfile/​rewrite.go	Implements checkout validation.
internal/​workflowfile/​rewrite_test.go	Tests ordering, scope, and aliases.
cmd/​gh-actions-lock/​migrate_test.go	Verifies atomic CLI failure.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jessehouwing]

This would also require checking if any workflow hits that composite action with a custom checkout step, not just the one being migrated.

[kuma0128]

Thanks, this is covered in 70c32f8. All workflows are checked before shared composite actions are rewritten, with a regression test confirming that a custom-ref checkout in an unselected workflow blocks migration without changing any files.

[jessehouwing]

For pull_request_target, is there a special case needed here? I'm not yet entirely clear which ref "$/" points to in that special case.

[kuma0128]

@jessehouwing
Based on the documented semantics, the existing guard covers this. In the workflow triggered by pull_request_target, $/ resolves to the default-branch commit (github.sha), regardless of the PR's base branch.
A same-repo checkout with no ref or ref: ${{ github.sha }} matches it; an explicit ref: ${{ github.event.pull_request.head.sha }} already blocks migration.

[Copilot]

🟡 Changes recommended

Caller discovery misses the configured workflow directory, allowing unsafe shared-action migrations in scoped runs.

2 open findings

• Checkout context is not propagated into composite action migrations
• Caller discovery ignores GH_ACTIONS_LOCK_WORKFLOWS_DIR · New

🧠 Review effort: Balanced