nodeselector · Jul 24, 2026 · Jul 13, 2026 · Jul 14, 2026 · Jul 24, 2026 · Jul 24, 2026
@@ -33,6 +33,19 @@ After the initial run to onboard workflows, you will need to run `gh actions-loc
 - A new workflow is created that has `uses` dependencies.
 - An existing workflow adds or removes `uses` dependencies.
 
+Pins to branches or partial versions (e.g. `main`, `v4`) are trusted from the
+lockfile and not re-resolved on a normal run. To bump them to the current
+upstream commit, run:
+
+```bash
+gh actions-lock --relock
+```
+
+`--relock` re-resolves refs that have legitimately moved and rewrites the
+lockfile to the new SHA. Suspicious pins whose recorded commit is no longer
+reachable upstream are left as errors — use `--accept-moved` to re-resolve
+those as well.
+
 ### Self repository actions (`$/…`)
 
 `uses: $/…` references an action or reusable workflow in the **same repository** as

@@ -1067,3 +1067,93 @@ func TestCheckCommand_JSONLoadErrorIsInvalid(t *testing.T) {
 	require.Len(t, payload.Findings, 1)
 	assert.Equal(t, "error", payload.Findings[0].Severity)
 }
+
+// TestCheck_Relock_BumpsMovedBranchRef covers github/actions-dispatch#751:
+// a branch ref (main) whose upstream head advanced is trusted as-is on a
+// normal run and merely flagged ref-moved under --rescan. --relock must
+// re-resolve it and rewrite the lockfile to the new live SHA.
+func TestCheck_Relock_BumpsMovedBranchRef(t *testing.T) {
+	reg := &httpmock.Registry{}
+
+	staleSHA := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+	liveSHA := "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+
+	reg.Register(
+		httpmock.GraphQLForRepo("example", "action"),
+		httpmock.JSONResponse(map[string]any{
+			"data": map[string]any{
+				"a0": testRepoResponse("example/action", liveSHA, nodeActionYAML),
+			},
+		}),
+	)
+	// staleSHA is a legitimate ancestor of liveSHA (branch advanced) → ref-moved.
+	reg.Register(
+		httpmock.REST("GET", "repos/example/action/compare/"),
+		httpmock.JSONResponse(map[string]any{
+			"status": "ahead",
+			"merge_base_commit": map[string]any{
+				"sha": staleSHA,
+			},
+		}),
+	)
+	// Reverse-lookup stubs: main resolves to the live head; no tags.
+	reg.Register(
+		httpmock.REST("GET", "repos/example/action/branches"),
+		httpmock.JSONResponse([]any{
+			map[string]any{"name": "main", "commit": map[string]any{"sha": liveSHA}},
+		}),
+	)
+	reg.Register(
+		httpmock.REST("GET", "repos/example/action/tags"),
+		httpmock.JSONResponse([]any{}),
+	)
+
+	workflowPath := writeTempWorkflow(t, `
+name: ci
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: example/action@main
+`,
+		"example/action@main=sha1-"+staleSHA,
+	)
+
+	stdout, _, err := runCommandWithHTTP(t, reg,
+		"--relock", "--no-narrow", workflowPath,
+	)
+	require.NoError(t, err, "stdout:\n%s", stdout)
+
+	pins := readTempLockfilePins(t)
+	assert.Contains(t, pins, liveSHA, "--relock should rewrite the lockfile to the live SHA")
+	assert.NotContains(t, pins, staleSHA, "--relock should drop the stale SHA")
+}
+
+// TestCheck_DefaultRun_DoesNotBumpBranchRef is the counterpart to the relock
+// test: without --relock a mutable branch ref is trusted from the lockfile
+// (fast path, no network) and its recorded SHA is left as-is.
+func TestCheck_DefaultRun_DoesNotBumpBranchRef(t *testing.T) {
+	reg := &httpmock.Registry{}
+	defer reg.Verify(t) // no stubs should be hit on the fast path
+
+	staleSHA := "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+	workflowPath := writeTempWorkflow(t, `
+name: ci
+on: push
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: example/action@main
+`,
+		"example/action@main=sha1-"+staleSHA,
+	)
+
+	_, _, err := runCommandWithHTTP(t, reg, workflowPath)
+	require.NoError(t, err)
+
+	assert.Contains(t, readTempLockfilePins(t), staleSHA,
+		"a default run must not bump a trusted branch ref")
+}
@@ -56,6 +56,11 @@ type checkOptions struct {
 	// ref-moved: prunes the stale lockfile entry and re-pins to the
 	// current live SHA.
 	acceptMoved bool
+	// relock re-resolves deps whose branch or partial-version ref has
+	// legitimately advanced (ref-moved) to the current upstream SHA.
+	// Unlike acceptMoved it does NOT accept unreachable-pin findings
+	// (possible tampering), which stay hard errors.
+	relock bool
 	// verify is a convenience alias for --rescan --no-fix: full
 	// re-verification of every pin with a non-zero exit on any finding.
 	verify bool
@@ -84,6 +89,7 @@ func bindCheckFlags(cmd *cobra.Command, opts *checkOptions) {
 	cmd.Flags().StringSliceVar(&opts.allowRunners, "allow-runners", nil, "Deprecated no-op: runner restrictions have been removed")
 	cmd.Flags().BoolVarP(&opts.allowAllRunners, "allow-all-runners", "A", false, "Deprecated no-op: runner restrictions have been removed")
 	cmd.Flags().BoolVar(&opts.acceptMoved, "accept-moved", false, "Re-resolve deps flagged as ref-moved or unreachable-pin to their current live SHA")
+	cmd.Flags().BoolVar(&opts.relock, "relock", false, "Bump moved branch/version refs (e.g. main, v4) to their current upstream SHA; leaves unreachable pins as errors")
 	cmd.Flags().BoolVar(&opts.verify, "verify", false, "Full re-verification of every pin (equivalent to --rescan --no-fix)")
 	cmd.Flags().BoolVar(&opts.verifyLocal, "verify-local", false,
 		"Offline lockfile coverage check: verify every action ref has a lockfile entry.\n"+
@@ -103,11 +109,8 @@ func (opts *checkOptions) validateOutputFlags() error {
 	if opts.verify && opts.verifyLocal {
 		return fmt.Errorf("--verify and --verify-local are mutually exclusive")
 	}
-	if opts.verifyLocal && opts.rescan {
-		return fmt.Errorf("--verify-local is offline and cannot be combined with --rescan")
-	}
-	if opts.verifyLocal && opts.acceptMoved {
-		return fmt.Errorf("--verify-local is offline and cannot be combined with --accept-moved")
+	if opts.verifyLocal && (opts.rescan || opts.acceptMoved || opts.relock) {
+		return fmt.Errorf("--verify-local cannot be combined with --rescan, --accept-moved, or --relock because it runs offline")
 	}
 	return nil
 }
@@ -171,8 +174,9 @@ func runCheck(cmd *cobra.Command, opts *checkOptions, newResolver resolverFunc)
 	// Pre-warm resolver caches from the lockfile so repeat runs skip
 	// redundant GraphQL and REST calls. Skipped when --rescan is set:
 	// a full re-verification must hit the network to detect ref movement.
-	// --accept-moved implies --rescan (must detect what moved).
-	if opts.acceptMoved {
+	// --accept-moved and --relock both imply --rescan (must detect what
+	// moved before re-pinning).
+	if opts.acceptMoved || opts.relock {
 		opts.rescan = true
 	}
 	trustLockfileCaches := !opts.rescan
@@ -337,6 +341,7 @@ func runCheck(cmd *cobra.Command, opts *checkOptions, newResolver resolverFunc)
 		Version:     cliVersion(),
 		NoNarrow:    opts.noNarrow,
 		AcceptMoved: opts.acceptMoved,
+		Relock:      opts.relock,
 	})
 	endPlan()
 	if planErr != nil {

@@ -62,6 +62,11 @@ func TestValidateOutputFlags_VerifyConflicts(t *testing.T) {
 			opts:    checkOptions{verifyLocal: true, acceptMoved: true},
 			wantErr: "offline",
 		},
+		{
+			name:    "verify-local and relock conflict",
+			opts:    checkOptions{verifyLocal: true, relock: true},
+			wantErr: "offline",
+		},
 		{
 			name: "verify alone is valid",
 			opts: checkOptions{verify: true},

@@ -35,6 +35,12 @@ type PlanOptions struct {
 	// re-resolved to their current live SHA.
 	AcceptMoved bool
 
+	// Relock treats ref-moved findings (a branch or partial-version ref
+	// that legitimately advanced) as resolvable, re-pinning them to the
+	// current live SHA. Unlike AcceptMoved it leaves unreachable-pin
+	// findings untouched so possible tampering stays a hard error.
+	Relock bool
+
 	// prevImpreciseNWO is computed once in Plan() from the global lockfile
 	// state. It holds lowercased NWOs that are already recorded with a
 	// non-full-semver ref anywhere in the lockfile. Narrowing is skipped
@@ -129,19 +135,44 @@ func planWorkflow(ctx context.Context, wr checks.WorkflowReport, opts PlanOption
 
 	// Drop stale inventory entries so a re-pin converges: the orphan leaves
 	// workflows[path] and Save's GC removes its dependencies[] entry.
-	inventory := pruneStaleInventory(wr.Inventory, wr.Findings, opts.AcceptMoved)
+	inventory := pruneStaleInventory(wr.Inventory, wr.Findings, opts.AcceptMoved, opts.Relock)
+	repinMoved := repinsMoved(opts) && wr.CountByCategory(checks.RefMoved) > 0
 
-	if !wr.NeedsAttention() {
+	if !wr.NeedsAttention() && !repinMoved {
 		entries = verifiedEntries(inventory, wr.Path)
 		rw := narrowVerifiedEntries(ctx, entries, opts, rewriteRefKeys)
 		wplans = append(wplans, WorkflowPlan{Path: wr.Path, Rewrites: rw})
 		return planResult{entries: entries, wplans: wplans}, nil
 	}
 
+	// --relock must not rewrite a workflow that still carries an
+	// unreachable-pin finding: re-resolving a moved sibling pulls the whole
+	// tree (including the possibly-tampered unreachable dep, which may be
+	// transitive and absent from the direct-only inventory) through
+	// ResolveAllRecursive, and buildPinnedEntries would commit it at a live
+	// SHA before the hard-error gate runs. Leave the workflow untouched from
+	// its original inventory; the unreachable-pin error still fails the run.
+	// --accept-moved deliberately accepts these, so it is exempt.
+	if opts.Relock && !opts.AcceptMoved && wr.CountByCategory(checks.UnreachablePin) > 0 && repinMoved {
+		entries = verifiedEntries(wr.Inventory, wr.Path)
+		wplans = append(wplans, WorkflowPlan{Path: wr.Path})
+		return planResult{entries: entries, wplans: wplans}, nil
+	}
+
 	// Per-dep trust: recorded deps skip the network path.
 	unrecordedRefs, inventorySHA := partitionByInventory(inventory, wr.ActionRefs)
 	entries = verifiedEntries(inventory, wr.Path)
 
+	// A moved *transitive* dep is pruned from inventory but is not a direct
+	// ActionRef, so partitionByInventory marks nothing unrecorded and the
+	// verified fast path would silently drop it instead of bumping it. Force
+	// the workflow's direct roots through recursive resolution so the moved
+	// transitive is re-pinned to its current SHA.
+	if len(unrecordedRefs) == 0 && repinMoved {
+		unrecordedRefs, inventorySHA = partitionByInventory(nil, wr.ActionRefs)
+		entries = verifiedEntries(nil, wr.Path)
+	}
+
 	if len(unrecordedRefs) == 0 {
 		rw := narrowVerifiedEntries(ctx, entries, opts, rewriteRefKeys)
 		wplans = append(wplans, WorkflowPlan{Path: wr.Path, Rewrites: rw})
@@ -253,7 +284,7 @@ func planWorkflow(ctx context.Context, wr checks.WorkflowReport, opts PlanOption
 	entries = append(entries, buildPinnedEntries(opts, wr, deps, parentMap, rootTracker, inventorySHA)...)
 
 	// Record findings that are informational (ref-moved, misleading-sha).
-	entries = append(entries, informationalEntries(wr)...)
+	entries = append(entries, informationalEntries(wr, opts)...)
 
 	return planResult{entries: entries, wplans: wplans}, nil
 }
@@ -483,32 +514,43 @@ func buildPinnedEntries(opts PlanOptions, wr checks.WorkflowReport, deps []dep.D
 }
 
 // informationalEntries records ref-moved and misleading-sha findings as
-// Investigate entries.
-func informationalEntries(wr checks.WorkflowReport) []Entry {
+// Investigate entries. When the run re-pins moved refs (--relock or
+// --accept-moved), ref-moved is resolved by the re-pin and is not recorded
+// for investigation.
+func informationalEntries(wr checks.WorkflowReport, opts PlanOptions) []Entry {
 	var out []Entry
 	for _, f := range wr.Findings {
 		switch f.Category {
-		case checks.MisleadingSHA, checks.RefMoved:
-			nwo := ""
-			ref := ""
-			if f.ActionRef != nil {
-				nwo = f.ActionRef.Owner + "/" + f.ActionRef.Repo
-				ref = f.ActionRef.Ref
+		case checks.RefMoved:
+			if repinsMoved(opts) {
+				continue
 			}
-			out = append(out, Entry{
-				NWO:         nwo,
-				Ref:         ref,
-				ObservedSHA: f.ObservedSHA,
-				Resolution:  Investigate,
-				Issue:       string(f.Category),
-				Reason:      f.Detail,
-				Workflows:   []string{wr.Path},
-			})
+			out = append(out, informationalEntry(f, wr.Path))
+		case checks.MisleadingSHA:
+			out = append(out, informationalEntry(f, wr.Path))
 		}
 	}
 	return out
 }
 
+func informationalEntry(f checks.Finding, path string) Entry {
+	nwo := ""
+	ref := ""
+	if f.ActionRef != nil {
+		nwo = f.ActionRef.Owner + "/" + f.ActionRef.Repo
+		ref = f.ActionRef.Ref
+	}
+	return Entry{
+		NWO:         nwo,
+		Ref:         ref,
+		ObservedSHA: f.ObservedSHA,
+		Resolution:  Investigate,
+		Issue:       string(f.Category),
+		Reason:      f.Detail,
+		Workflows:   []string{path},
+	}
+}
+
 // partitionByInventory splits refs into those with a matching inventory
 // entry (recorded) and those without (unrecorded). Returns the unrecorded
 // refs and an NWO:SHA index for deduplicating resolved deps later.
@@ -531,17 +573,23 @@ func partitionByInventory(inventory []checks.InventoryEntry, refs []parserlock.A
 
 // pruneStaleInventory drops inventory entries matching a stale finding (a pin
 // the workflow no longer references), so a fix-mode re-pin converges.
-func pruneStaleInventory(inventory []checks.InventoryEntry, findings []checks.Finding, acceptMoved bool) []checks.InventoryEntry {
+// acceptMoved additionally prunes ref-moved and unreachable-pin deps; relock
+// prunes ref-moved deps only, so a benign branch/version advance can be
+// re-pinned without accepting a possibly-tampered unreachable pin.
+func pruneStaleInventory(inventory []checks.InventoryEntry, findings []checks.Finding, acceptMoved, relock bool) []checks.InventoryEntry {
 	stale := make(map[string]bool)
 	for _, f := range findings {
 		switch {
-		case f.Category == checks.Stale && f.Dependency != nil:
-			d := f.Dependency
-			stale[strings.ToLower(d.NWO+"@"+d.Ref+":"+d.SHA)] = true
-		case acceptMoved && (f.Category == checks.UnreachablePin || f.Category == checks.RefMoved) && f.Dependency != nil:
-			d := f.Dependency
-			stale[strings.ToLower(d.NWO+"@"+d.Ref+":"+d.SHA)] = true
+		case f.Dependency == nil:
+			continue
+		case f.Category == checks.Stale,
+			f.Category == checks.UnreachablePin && acceptMoved,
+			f.Category == checks.RefMoved && (acceptMoved || relock):
+		default:
+			continue
 		}
+		d := f.Dependency
+		stale[strings.ToLower(d.NWO+"@"+d.Ref+":"+d.SHA)] = true
 	}
 	if len(stale) == 0 {
 		return inventory
@@ -557,6 +605,11 @@ func pruneStaleInventory(inventory []checks.InventoryEntry, findings []checks.Fi
 	return out
 }
 
+// repinsMoved reports whether this run re-resolves benign ref-moved deps.
+func repinsMoved(opts PlanOptions) bool {
+	return opts.Relock || opts.AcceptMoved
+}
+
 // verifiedEntries builds Verified plan entries for every inventory item.
 func verifiedEntries(inventory []checks.InventoryEntry, path string) []Entry {
 	out := make([]Entry, len(inventory))