Lint GitHub Actions workflows on pull requests, and test the parsed Publish job

[MaxGhenis]

Summary

• Lint workflows on every PR. A new "Lint workflows" job in .github/workflows/pr.yaml runs actionlint 1.7.12, the latest release (2026-03-30). It uses the official rhysd/actionlint image pinned by digest sha256:b1934ee5…; on Docker Hub, both the 1.7.12 and latest tags resolve to that digest. The image bundles shellcheck and pyflakes, so actionlint also checks run: scripts. The job runs with contents: read, and its checkout doesn't keep the token (persist-credentials: false).
• Fix the two actionlint warnings on master:
  • SC2046 in push.yaml, versioning job, "Build changelog" step: the $(python -c …) passed to towncrier build --version is now quoted. The Makefile changelog target had the same pattern and is quoted too.
  • Deprecated input in Publish: skip_existing is now skip-existing. In pypa/gh-action-pypi-publish@release/v1's action.yml, skip-existing is the canonical input; skip_existing is a deprecated alias passed through as inputs.skip-existing || inputs.skip_existing, so behavior is unchanged.
• The release-ordering test parses YAML. test_publish_workflow_tags_only_after_pypi_succeeds used to slice the file text from " Publish:\n" to the end. It now asserts on yaml.safe_load(PUSH_WORKFLOW.read_text())["jobs"]["Publish"].
• Passes today, not only after Deploy the documentation site from its own release job #594. .github/actionlint.yaml ignores two error messages, in push.yaml only. Both come from the Test job's "Deploy documentation" step, which Deploy the documentation site from its own release job #594 fixes.
• The README's development section gives the local actionlint command, pinned to the same 1.7.12. Run it from the repo root: actionlint matches the ignores against paths relative to the working directory.

Background: #594 fixes a release step that was skipped on every release since 2024-09-26. It was guarded by if: matrix.os == 'ubuntu-latest' in a job with no matrix, and actionlint reports exactly that (property "os" is not defined in object type {}).

Why the two ignores

Without them, Lint workflows would fail on every PR until #594 merges, and #594 waits on a go/no-go about resuming the public docs site. The two ignored errors are the matrix.os condition and the GITHUB_TOKEN input, which JamesIves/github-pages-deploy-action@v4 does not define. actionlint matches ignores by message only, so these are as narrow as it allows: one file and two exact messages.

The cost: until the entries are deleted, a new matrix.<key> reference in a matrix-less job in push.yaml would also be ignored. I checked this by adding one to Publish; actionlint stayed clean. pr.yaml and every other check are unaffected. #594's own tests/core/test_docs_deployment.py asserts that no job in either workflow references an undefined matrix key, so once #594 lands that bug is covered even if the ignore lingers. The config comment says to delete both entries in whichever PR fixes or removes the step.

The test rewrite

The parsed test asserts, on Publish only:

Property	Why
permissions.contents == "write" (or write-all)	The tag script pushes a tag; another job's permissions don't apply.
checkout fetch-depth is 0 (compared as a string, since action inputs are strings)	.github/publish-git-tag.sh looks for an existing tag locally, and a checkout with fetch-depth: 0 fetches every tag.
tag step after the PyPI step	Steps run in order, and a failure skips the rest.
no if: on either step; no continue-on-error on the PyPI step	Any of these lets the tag step run without a successful upload. A skipped step doesn't fail the job, so an if: that skips the upload (say github.ref == 'refs/heads/main' on this master repo) still lets the tag through.
no continue-on-error on the tag step; its run is exactly bash .github/publish-git-tag.sh	A failed tag push must fail the job. The exact match rejects || true, || exit 0, set +e and the like.

Exactly one checkout, one PyPI and one tag step must exist, each with a message naming what's missing. The if: and continue-on-error checks go beyond the brief: they close the remaining ways the tag could run without a successful upload.

Eight parametrized mutation cases each break one property and assert that the check fails with that property's message, so no assertion is vacuous. Two more cases check that equivalent settings (permissions: write-all, fetch-depth: "0") pass. The first case is the false pass from the review of #594: Publish's permissions deleted and a later Docs job with contents: write.

That false pass, on the real file (master's push.yaml with Publish's permissions block removed and a Docs job appended after Publish):

old text-slice test:  1 passed
new parsed test:      AssertionError: Publish lacks contents: write

Merge order

• Deploy the documentation site from its own release job #594: merges cleanly in either order (checked locally). Its PR should then delete the two entries in .github/actionlint.yaml, or a one-line follow-up does.
• Publish a release only after its tests pass #591: conflicts in tests/core/test_release_tagging.py, and only there, in both orders. Publish a release only after its tests pass #591 appends its test at the end of the file, right after the test this PR replaces. Whichever lands second keeps both tests: this PR's file, with Publish a release only after its tests pass #591's test appended. Publish a release only after its tests pass #591's import yaml line is identical to this PR's. That combined tree (master + Publish a release only after its tests pass #591 a093ae0b + this PR) passes 16 tests, and actionlint finds nothing.

Checks run

• actionlint 1.7.12 (uvx --from actionlint-py==1.7.12.25 actionlint, shellcheck 0.11.0):
  • master: 4 findings.
  • this head: 0 (exit 0).
  • this head with an empty config: exactly the 2 Deploy the documentation site from its own release job #594 findings.
• Mutation check of the lint job: restoring each fix brings back its exact master finding (SC2046:warning:3:33; the deprecated-input error). A matrix.os condition in a pr.yaml job and a needs: typo each fail.
• The quoted towncrier commands, run for real in throwaway worktrees with a fragment (make changelog, and the push.yaml step script extracted from the parsed YAML): both bump to 3.32.21. The CHANGELOG.md and pyproject.toml they produce are byte-identical to master's unquoted command.
• pytest tests/core/test_release_tagging.py: 15 passed (Python 3.13). The edge cases the review raised: write-all and fetch-depth: "0" pass; read-all, fetch-depth: false, fetch-depth: 1, || exit 0 and set +e each fail on their own message.
• uvx ruff format --check .: 339 files already formatted. ruff check on the test file: clean.
• CI on this head: queued at hand-off. Every PolicyEngine repo is waiting for runners: policyengine-us alone had 44 runs queued, with 2 in progress org-wide.

Not run locally: the Docker image (Docker isn't running on the machine that made this change). The config should still apply in CI, for three reasons:

• Config loading: actionlint v1.7.12, run with no file arguments, finds the project root by walking up to a directory with both .github/workflows and .git (project.go), then loads .github/actionlint.yaml from it (config.go).
• Glob matching: it matches the paths: glob against each file's path relative to the working directory (linter.go).
• Working directory: this job's earlier run on cf8fb6a1 started the container with --workdir /github/workspace and reported .github/workflows/push.yaml:79:13, so the glob sees exactly .github/workflows/push.yaml.

The first green Lint workflows run on this PR will confirm it.

Review

An independent Opus review on Subfleet (20261006-172501-core597-review) of d67d103f returned APPROVE WITH NITS. That reviewer had no shell, so it worked from source. The commit after it, cbb88b57, fixes all its nits:

• the "fetch-depth 0 fetches tags only" wording, since checkout's fetch-tags also fetches tags;
• fetch-depth: false passing as 0;
• write-all raising AttributeError;
• matching the tag script exactly instead of a || true regex;
• the README pin.

Its last finding, deleting the stale ignores once #594 lands, is a merge step. It's covered above and in a comment on #594.

A second reviewer, an in-session Opus agent that ran every command above, reviewed cbb88b57 and returned APPROVE WITH NITS. It reproduced the false pass and traced the paths: matching through actionlint's source and the cf8fb6a1 CI log. b7c4977f fixes its nits:

• a PyPI-step if: let the tag through;
• write-all and "0" had no passing test;
• the README didn't say to run from the repo root;
• the lint job could drop its write token.

The same reviewer approved b7c4977f, and then approved 9a30bd55, which changes one word of a comment.

This PR combines two sessions started from the same follow-up. The first opened it with the lint job and the two fixes (cf8fb6a1). The second added the test rewrite, the ignore config, the hardening and the README line (d67d103f onward).

Documentation review

• Documentation changes: the README's development section gains the local actionlint command. No other durable docs describe the PR checks.
• Impact: low. CI and tests only; no package code changes.
• Confidence: high. Every claim above comes from a command run on this head or from the action's action.yml.

axiom: n/a: CI workflow and test change, no policy change

🤖 Generated with Claude Code

[MaxGhenis]

Hand-off to the US + core hub.

• Head: 9a30bd555b9766864f6cc0a0b834cac9605b242e, base master 757147c7. The PR is MERGEABLE and not a draft.
• Review:
  • Subfleet Opus 20261006-172501-core597-review returned APPROVE WITH NITS on d67d103f. Its nits are fixed in cbb88b57.
  • An in-session Opus agent, which ran every command, returned APPROVE WITH NITS on cbb88b57. Its nits are fixed in b7c4977f.
  • The same agent returned APPROVE on b7c4977f and on 9a30bd55, a one-word comment change.
• Passed locally at this head:
  • actionlint 1.7.12: exit 0. With an empty config, exactly the 2 Deploy the documentation site from its own release job #594 errors.
  • pytest tests/core/test_release_tagging.py: 15 passed.
  • ruff format --check .: clean.
  • Old vs new test on the false-pass mutation: the old test passes, the new one fails.
• Pending: all CI. It is queued behind the org-wide runner backlog, so nothing has failed. Lint workflows is the first CI run with .github/actionlint.yaml. Source reading and the cf8fb6a1 job log both say the ignores apply in the container (cwd /github/workspace). If it fails anyway, the cause is that config, not the workflows.
• Merge order, no dependency:
  • Publish a release only after its tests pass #591 conflicts with this PR in tests/core/test_release_tagging.py only. Whichever lands second takes this PR's file with Publish a release only after its tests pass #591's test appended. That combined tree passes 16 tests.
  • Deploy the documentation site from its own release job #594 merges cleanly with this PR in either order. Once both have landed, delete .github/actionlint.yaml, which only holds Deploy the documentation site from its own release job #594's two ignores. Details are in my comment on Deploy the documentation site from its own release job #594.
• Holds and decisions: none for this PR. Deploy the documentation site from its own release job #594 itself waits on d1028.
• Follow-ups, already filed as chips: remove the dead .github/*.sh release scripts and shellcheck the live one; declare PyYAML as a direct dependency.

Review records, the #591 resolution and the drafts are in ~/reviews/policyengine-core-597/ on Max's machine.

[MaxGhenis]

US + core hub merge audit, core#597 at 9a30bd555b9766864f6cc0a0b834cac9605b242e (squash)

• Reviews:
  • Subfleet Opus APPROVE WITH NITS at d67d103; the nits were fixed in cbb88b5.
  • An in-session Opus agent, which ran every command, returned APPROVE WITH NITS at cbb88b5; the nits were fixed in b7c4977. It then returned APPROVE at b7c4977 and at 9a30bd5.
  • The hub checked b7c4977..9a30bd5: a one-word comment change ("would" → "could").
• Hand-off: from local_eae2eb38. No hold or decision.
• Gates checked live at merge:
  • gh pr checks exits 0 (19 pass), including the first Lint-workflows run with .github/actionlint.yaml;
  • MERGEABLE, and merges clean with current master;
  • not a draft;
  • no CHANGES_REQUESTED review;
  • head pinned.
• Impact: CI and tests only; no model output change.
• Merge order: Publish a release only after its tests pass #591 conflicts in tests/core/test_release_tagging.py only. It lands second, taking this file with Publish a release only after its tests pass #591's test appended. After Deploy the documentation site from its own release job #594 also lands, delete .github/actionlint.yaml.