What the agent does
The agent clones the repository into its own cloud sandbox and reads every workflow under .github/workflows/. In a C++ library like jarro2783/cxxopts there are four. build.yml checks out with actions/checkout@v4 and runs three shell steps, cd build; cmake .., cd build; make -j$(nproc) and cd build; ctest. cmake.yml sets defaults.run.shell: bash, runs a matrix of two Ubuntu releases against g++-9, g++-10 and clang++ with install steps guarded by which, and separate macOS and Windows jobs where the Windows one runs cd $BUILD_TYPE && ./link_test && ./options_test. meson.yml is on actions/checkout@v6 and actions/setup-python@v5 with BSFishy/meson-build@v1.0.3 at two Meson versions and ilammy/msvc-dev-cmd@v1 for MSVC. cifuzz.yml runs on every pull_request, builds and runs fuzzers through google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master and run_fuzzers@master, and uploads crashes with actions/upload-artifact@v4 under if: failure() && steps.build.outcome == 'success'. There is no .github/dependabot.yml and no linter for the workflows themselves, so a typo in an expression, a misspelled input or a shell step that silently keeps going after a failed cd is found only when the workflow runs.
It downloads the actionlint binary with the project's download-actionlint.bash script, installs shellcheck, which actionlint calls on every run: step, and runs actionlint -color over the four files. Then it reads each finding against the workflow rather than fixing blindly. shellcheck flags the cd build; cmake .. pattern in build.yml because a failed cd lets the next command run in the wrong directory; the agent rewrites those three steps with working-directory: build, which is the Actions way to say the same thing and removes the cd entirely. Expression and input findings, a with: key an action does not declare or a context property that does not exist, are fixed in place, and anything actionlint reports that the agent judges to be a false positive, such as a shell idiom the repository uses deliberately, gets an inline # shellcheck disable= with a reason rather than a global ignore. Each change is listed in the pull request with the finding that caused it.
Then it adds .github/workflows/actionlint.yml: a job on pull_request and on push to master, with paths limited to .github/workflows/** so it costs nothing on code changes, that checks out the repository, installs the pinned actionlint release and shellcheck, registers the problem matcher that ships with actionlint so findings appear as annotations on the changed lines, and runs actionlint -color. It adds an .github/actionlint.yaml only if the repository needs one, for self-hosted runner labels or a Python checker setting, which this one does not, and says so. Because the four workflows are on three different actions/checkout majors, the agent notes that actionlint does not check versions and that a Dependabot config for the github-actions ecosystem would, without adding one, since that is a separate change the reader may already have an opinion on.
The check of its own work is the tool itself: the agent re-runs actionlint over all five workflows, including the new one, until it reports nothing, and pastes the before and after output into the pull request. It also runs shellcheck directly on the one-line scripts it rewrote to show the specific codes that cleared, and renders the matrix in cmake.yml with actionlint -format to show the job and step names still resolve after the edits.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add actionlint to this repository's CI. Read every file under .github/workflows and any .github/actionlint.yaml or dependabot.yml first. Download the actionlint binary with the project's download script, install shellcheck, and run actionlint over all the workflows. Fix each finding in place, preferring working-directory over cd in shell steps and keeping expressions and action inputs correct; where a finding is a deliberate idiom, add an inline shellcheck disable with a reason instead of a global ignore. Add a workflow that runs the pinned actionlint release with shellcheck on pull requests and pushes to the default branch, limited to changes under .github/workflows, with the problem matcher registered so findings show as annotations. Add an actionlint config file only if the repository needs one and say why. Note any version drift between actions that actionlint does not check, without adding a Dependabot config. Re-run actionlint until it is clean and open a pull request with the before and after output and one line per fix naming the finding behind it.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request adding .github/workflows/actionlint.yml and editing the existing workflows only where actionlint reported something, such as the three cd build; steps in build.yml becoming working-directory: build. No build, test or fuzzing logic changes, and every edit is paired in the description with the finding that caused it, so a reviewer can judge each one against the tool's output rather than the agent's taste.
The description pastes the first actionlint run with its findings and the final run that reports nothing, the shellcheck codes that cleared on the rewritten steps, and the one observation the tool cannot make, that the workflows are on three actions/checkout majors, left as a note rather than a change.
Before merging, a reviewer looks at the new workflow's first run on the pull request itself, since it lints its own file, decides whether the actionlint check should be required for merge, and whether to take up the Dependabot suggestion as a follow-up.
Run it on every pull request that changes a workflow
In the console, an automation in the Project that has the repository, with a github trigger on pull_request.opened and pull_request.synchronize, starts one run per pull request with the event after the prompt. The prompt asks the run to finish at once unless a file under .github/workflows/ changed, and otherwise to run actionlint on the pull request's branch and leave a review comment that explains each finding in plain words, with the fix, which is what the CI annotation cannot do when the author has not met the tool before.
From your own server, send this body as POST /o/{org}/sessions with the repository in resources for each repository in the organisation, with a request_id that is a UUID v5 of the repository name so a retried call returns the run it already started. Set a webhook_url on the key to receive run.completed with data.session_url when each pull request is open.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Adding a linter is easy; adding one that passes on the first run means reading every finding it raises against workflows nobody has touched in a while and deciding, one by one, whether to fix or to justify. The agent does that reading in its sandbox with the real tool and the real shellcheck, and the before and after output is in the run's record beside the pull request, so the check arrives green and the reviewer sees exactly what it cost to get there.
The same request runs across every repository in an organisation at once, each in its own sandbox with its own workflows and its own findings, which is how a team gets a workflow linter everywhere in one review cycle, with each pull request listing only the fixes that repository needed.
Frequently asked questions
Will actionlint change how my workflows behave?
Only where it found a real problem. Replacing cd build; with working-directory: build runs the same command in the same directory and stops a failed cd from running the next command elsewhere. Every edit is listed with its finding so you can revert any you disagree with.
Does it also check that my actions are up to date?
No. actionlint validates syntax, expressions, action inputs, runner labels and the shell in run: steps. Version drift, such as workflows on different actions/checkout majors, is Dependabot's job, and the agent notes the drift without adding a Dependabot config unless you ask.
What about findings that are false positives?
The agent adds an inline # shellcheck disable= with the code and a one-line reason at the step that needs it, never a repository-wide ignore, so the suppression is visible next to the code it covers and the rest of the file is still checked.
Why not run actionlint through a pre-commit hook instead?
A CI job catches every contributor, including those who never installed the hook. The workflow is limited to changes under .github/workflows/, so it runs only when a workflow moves. Adding a pre-commit hook beside it is a small follow-up if the team already uses pre-commit.
Does the new workflow lint itself?
Yes. It runs on any change under .github/workflows/, which includes its own file, and the agent runs actionlint over all five workflows before opening the pull request, so the first CI run is expected to pass.
More GitHub Actions jobs
More jobs like this: Hand off a long task
- Add the Admin UI to a Socket.IO Server (Socket.IO)
- Add Admonitions to an mdBook (mdBook)
- Add Analytics to an Astro Blog (Astro)