Summary
actionlint v1.7.12's shellcheck integration can hang indefinitely (not just run slowly — it does not return, even with a generous timeout) when a workflow's run: step contains a large quoted heredoc (e.g. cat > file << 'EOF' ... EOF) that inlines a big block of literal text.
What we found
This was hit concretely in .github/workflows/docs.yml's build job, which had a ~193-line quoted heredoc inlining a static HTML/CSS page for the docs site index. actionlint (invoked via lefthook run pre-commit) would hang indefinitely trying to process that run: script, blocking any commit that touched the file. Confirmed via bisection: reproduced identically against the pre-existing committed HEAD with zero other changes, so it was fully pre-existing and unrelated to any functional edit.
This specific instance is already fixed (see commit a73a386, "fix(ci): extract docs.yml build step's inline HTML to a static file" — extracts the heredoc body to .github/pages/docs-index.html and replaces it with a cp) — this issue is to track the underlying tooling gap, since the same shellcheck-hang could resurface if a future large heredoc gets added elsewhere in .github/workflows/.
Why it's not trivially avoidable today
There's no scoped, per-file way to disable just the shellcheck portion of actionlint in this version:
.github/actionlint.yaml's ignore: key only filters already-produced error messages — it doesn't prevent the hang, since the hang happens during shellcheck analysis, before any message is produced.- The
-shellcheck flag is all-or-nothing repo-wide; there's no way to disable it for one file/step while keeping it for the rest of the repo's workflows.
Suggested follow-up (informational / low priority)
- Watch for upstream fixes/reports against
actionlint's shellcheck integration for large heredocs.
- If another large inline heredoc gets added to a workflow in the future, prefer extracting static/literal content to a checked-in file (as done here) rather than inlining it, to avoid re-triggering this.
- Consider (if it ever becomes a recurring problem) whether a repo convention or lint-time size guard on inline heredocs in
run: steps is worth adding.
Priority
Low — informational/tracking only. No user-facing or CI-functional impact; the concrete instance that blocked commits is already resolved.
Precedent
Same pattern as #1160/#1161 (tracking a known tooling drift/gap as a standalone issue rather than letting it live only in a commit message).
Summary
actionlintv1.7.12's shellcheck integration can hang indefinitely (not just run slowly — it does not return, even with a generous timeout) when a workflow'srun:step contains a large quoted heredoc (e.g.cat > file << 'EOF' ... EOF) that inlines a big block of literal text.What we found
This was hit concretely in
.github/workflows/docs.yml'sbuildjob, which had a ~193-line quoted heredoc inlining a static HTML/CSS page for the docs site index.actionlint(invoked vialefthook run pre-commit) would hang indefinitely trying to process thatrun:script, blocking any commit that touched the file. Confirmed via bisection: reproduced identically against the pre-existing committed HEAD with zero other changes, so it was fully pre-existing and unrelated to any functional edit.This specific instance is already fixed (see commit a73a386, "fix(ci): extract docs.yml build step's inline HTML to a static file" — extracts the heredoc body to
.github/pages/docs-index.htmland replaces it with acp) — this issue is to track the underlying tooling gap, since the same shellcheck-hang could resurface if a future large heredoc gets added elsewhere in.github/workflows/.Why it's not trivially avoidable today
There's no scoped, per-file way to disable just the shellcheck portion of
actionlintin this version:.github/actionlint.yaml'signore:key only filters already-produced error messages — it doesn't prevent the hang, since the hang happens during shellcheck analysis, before any message is produced.-shellcheckflag is all-or-nothing repo-wide; there's no way to disable it for one file/step while keeping it for the rest of the repo's workflows.Suggested follow-up (informational / low priority)
actionlint's shellcheck integration for large heredocs.run:steps is worth adding.Priority
Low — informational/tracking only. No user-facing or CI-functional impact; the concrete instance that blocked commits is already resolved.
Precedent
Same pattern as #1160/#1161 (tracking a known tooling drift/gap as a standalone issue rather than letting it live only in a commit message).