Compiled lock files use `persist-credentials: false` on checkout steps — fails on repos with submodules

[jaroslawgajewski]

Description

The gh-aw compiler generates persist-credentials: false on all actions/checkout steps in compiled .lock.yml files. This causes workflow failures when the target repository uses git submodules.

Root Cause

actions/checkout v6 with persist-credentials: false runs git submodule foreach --recursive during post-step credential cleanup (removeToken → getSubmoduleConfigPaths in git-auth-helper.ts). This fails when:

1. The .gitmodules file is malformed (e.g., a submodule path entry with no url)
2. Submodule paths are absent in the working tree (common in sparse checkout mode)

The error looks like:

Error: fatal: No url found for submodule path '<path>' in .gitmodules

Reproduction

1. Create a repository with submodules (any valid .gitmodules + submodule directories)
2. Add any other agentic workflow targeting that repository
3. the workflow fails at the Checkout repository step during post-job cleanup

Current Workaround

We maintain a post-compile patch that replaces persist-credentials: false → persist-credentials: true on ALL actions/checkout steps across all compiled lock files.

Proposed Fix

The compiler should default to persist-credentials: true on all generated actions/checkout steps. Rationale:

• Runners are ephemeral — credentials left in git config are discarded after the job
• Credentials are re-configured anyway — every workflow has a "Configure Git credentials" step that sets up auth after checkout
• No security downgrade — the agent already has access to the GitHub token via MCP server and environment variables; persisting in git config doesn't expand the attack surface

Alternatively, expose a persist-credentials option in the workflow frontmatter so users can opt out if needed.

Environment

• gh-aw CLI: v0.71.5
• actions/checkout: v6.0.2
• Affected repositories: Any repo with git submodules

[pelikhan]

@salmanmkc feedback on actions/checkout

[pelikhan]

/scout investigate this issue and the checkout behavior with submodules

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan via /scout comment

Executive Summary

Confirmed: this is a long-standing, unfixed bug in actions/checkout (open since 2023). The bug is reproducible whenever (persist-credentials: false) + (broken or partially-present .gitmodules) combine — independent of gh-aw. gh-aw's compiler hardcodes persist-credentials: false in pkg/workflow/checkout_step_generator.go:119,166,251 for security reasons documented in ADR-29588, so the only way users hit by the bug can recover today is the post-compile patch they describe.

The security justification is real (the agent runs in the same job as the persisted GITHUB_TOKEN), so a blanket flip to persist-credentials: true is the wrong default. A targeted opt-out — either a frontmatter field or a different cleanup strategy that doesn't call git submodule foreach — is the recommended path.

Click to expand detailed findings

Research Findings

1. Upstream bug is real, open, and unowned

• actions/checkout#1358 — "No url found for submodule path in .gitmodules" (open since 2023-05-26, last activity 2025-04-28). A comment from @melinath confirms the trigger: "It only happens with persist-credentials: false set." @jsoref produced a workaround in check-spelling@6bbb7eb, and pinged @dscho (git/Microsoft) — who replied he is no longer at GitHub and lacks bandwidth.
• actions/checkout#788 — "Submodule with missing link in .gitmodules fails" (open since 2022) shows the same git submodule foreach failure even with persist-credentials: true and submodules: false — the auth-helper cleanup runs unconditionally.
• actions/checkout#2037 — "Git error from bad filenames on windows not revealed if persist-credentials is false" is a related instance of the cleanup path masking/causing extra failures.
• The bug path is removeToken → getSubmoduleConfigPaths in src/git-auth-helper.ts, as the issue author correctly identified. No upstream PR is targeting this.

Conclusion: an upstream fix is not coming on a useful timeline. gh-aw needs its own remedy.

2. Why gh-aw enforces persist-credentials: false

The enforcement is intentional, with three layers:

• Compiler emits it unconditionally: pkg/workflow/checkout_step_generator.go writes persist-credentials: false at lines 119 (sparse .github/.agents checkout), 166 (default workspace checkout), and 251 (additional checkouts).
• Test gate: pkg/workflow/checkout_persist_credentials_test.go:215 fails the build if any compiled checkout lacks persist-credentials: false.
• Codemod for user steps: pkg/cli/codemod_checkout_persist_credentials_false.go injects persist-credentials: false into user-authored actions/checkout steps in pre-steps/steps/post-steps/pre-agent-steps — but already honors an explicit persist-credentials: true (lines 366–371), confirming the user-opt-out pattern is acceptable.

The security rationale (per checkout_step_generator.go:165): "always disable credential persistence so the agent cannot exfiltrate credentials from disk." The agent runs in the same job and process tree as the runner, so any token left in .git/config is readable by the LLM-driven tools. This is not the same threat model as the ADR-29588 cleanup, which targets credentials from aws-actions/configure-aws-credentials, azure/login, etc.

3. The user's reproposed default is unsafe as a global change

The issue author argues:

"No security downgrade — the agent already has access to the GitHub token via MCP server and environment variables; persisting in git config doesn't expand the attack surface."

This is partially true but misses two cases:

• Workflows where the MCP server is configured with a scoped PAT (different from the runner GITHUB_TOKEN). The agent only gets the MCP token; .git/config would newly expose the workflow GITHUB_TOKEN.
• Workflows where safe-outputs substitutes a restricted token for the agent. Persisting the unrestricted token in git config breaks that isolation.

So a blanket default flip would weaken existing security guarantees for users who do not have submodules.

4. Recommended remedies (ordered by safety + scope)

Option A — Add a frontmatter opt-in (preferred). Expose checkout.persist-credentials: true in the schema and surface it in checkout_step_generator.go. The codemod already shows this pattern is supported on user-authored steps; extending it to gh-aw-generated checkouts is a small change. Document the security trade-off in docs/src/content/docs/reference/checkout.md. Repos with submodules opt in explicitly.

Option B — Replace the credential-cleanup mechanism (best long-term). Keep persist-credentials: true on the checkout step, then add a post-checkout step that does git config --local --unset-all (github.com/redacted) (and equivalent) directly — bypassing git submodule foreachentirely. This gives both the security property *and* submodule compatibility. It mirrors the targeted-cleanup pattern in ADR-29588 and the existingclean_git_credentials.sh` script referenced in the repo.

Option C — Auto-detect submodules and switch. Have the compiler probe for .gitmodules presence in the target repo at runtime via a pre-step, and conditionally adjust the cleanup. More magic, harder to audit, not recommended.

5. Existing repo signals supporting Option A/B

• ADR-29588 already establishes the pattern of targeted credential cleanup as a post-checkout responsibility, not as a persist-credentials: false setting.
• pkg/workflow/checkout_manager.go already exposes a submodules: "recursive" | "true" | "false" field — extending the frontmatter for one more persist-credentials boolean is consistent.
• The codemod in pkg/cli/codemod_checkout_persist_credentials_false.go already concedes user override is acceptable; the compiler-emitted checkouts should be consistent with that policy.

Recommendations

• Do not flip the default. The proposed-fix wording in the issue should be amended: keep persist-credentials: false as the default, expose an opt-in.
• Implement Option A first (frontmatter checkout.persist-credentials: true). Smallest delta, ships fast, unblocks the reporter and similar users.
• Track Option B as a follow-up to remove the trade-off entirely. Worth an ADR addendum to 29588 covering the actions/checkout-specific cleanup path.
• Add a regression test that compiles a workflow with the new opt-in and verifies the emitted persist-credentials: true.
• Document the trade-off explicitly in docs/src/content/docs/reference/checkout.md near the submodules: row in the Configuration Options table — that's where readers with submodule repos will look.
• Subscribe to No url found for submodule path in .gitmodules actions/checkout#1358 so the team is notified if upstream finally fixes it.

Key Sources

• actions/checkout#1358 — root upstream bug
• actions/checkout#788 — earlier instance, persists even with submodules: false
• actions/checkout#2037 — related side-effect of persist-credentials: false
• check-spelling@6bbb7eb — community workaround
• gh-aw pkg/workflow/checkout_step_generator.go — generator (lines 119, 166, 251)
• gh-aw pkg/cli/codemod_checkout_persist_credentials_false.go — codemod that already honors user override
• gh-aw ADR-29588 — existing targeted-cleanup pattern
• gh-aw checkout reference docs

Suggested Next Steps

1. Decide between Option A (frontmatter opt-in) and Option B (replace cleanup mechanism). Option A is recommended as the immediate ship.
2. Open a PR adding persist-credentials (boolean) to the checkout frontmatter schema (pkg/parser/schemas/main_workflow_schema.json), threading it through pkg/workflow/checkout_manager.go and emitting it conditionally in checkout_step_generator.go.
3. Update pkg/workflow/checkout_persist_credentials_test.go to allow true when the frontmatter opts in.
4. Document the trade-off in docs/src/content/docs/reference/checkout.md.
5. Consider opening a tracking issue for Option B (post-checkout targeted credential unset) and cross-link ADR-29588.

🔭 Intelligence gathered by Scout · ● 9.6M · ◷

[pelikhan]

@copilot add a front matter field to checkout "clean-git-credentials: true" that disables persists-credentials: false and injects a step that runs a script to remove git credentials compatible with submodules.