GitHub Actions
Run doctor as a GitHub Action
This repo is itself a composite action, so a consumer repo can gate on the audit without hand-writing the step:
- uses: actions/checkout@v7
- uses: rtorcato/repo-tooling@v6.0.1
That fails the job when doctor finds drift or missing config — the same exit
code you get from the CLI.
Inputs
| Input | Default | What it does |
|---|---|---|
directory | . | Directory to diagnose, relative to the workspace. |
fail-on | drift | drift fails on drift or missing; missing fails only on missing config; none annotates and never fails. |
Every finding becomes a job annotation regardless of fail-on, so none is the
report-only mode for a repo adopting the audit before it's clean:
- uses: rtorcato/repo-tooling@v6.0.1
with:
directory: packages/app
fail-on: none
Outputs
| Output | What it is |
|---|---|
json | The full doctor --json payload — feed it to a PR comment or a report. |
- uses: rtorcato/repo-tooling@v6.0.1
id: doctor
with:
fail-on: none
- run: jq '.results' <<< '${{ steps.doctor.outputs.json }}'
Versioning
Pin an exact release tag (@v5.4.1), not a floating major. The action
picks the CLI version from the ref you pinned (GITHUB_ACTION_REF, #759):
- A
v<semver>tag runs that CLI version —@v5.4.1runs CLI 5.4.1. The git ref is the only pin, and Dependabot'sgithub-actionsecosystem bumps the tag for you. - A branch or SHA pin runs
latest. A SHA pins the action's code, not the CLI it runs. - Tags before v5.4.1 ran CLI 3.11.0 whatever the tag said. They read the
version from
package.json, which is never bumped in git. Upgrade the pin to v5.4.1 or later.
The action runs doctor --offline, so checks that read live GitHub state are
skipped and never fail the step.
Notes
- The action runs
actions/setup-nodeinternally to guarantee Node 22, since the CLI requires it. That also sets Node for later steps in the same job — put the audit in its own job if that matters. - It's a composite action, not a Docker one:
doctoris a read-only file audit already published as an npm CLI, so a container would only add an image to build, publish and pull. doctornever executes the audited project's code — it reads config files.
Weekly drift issue
The PR gate only runs when a PR does. Drift that arrives with no PR, such as a
new upstream preset, goes unseen until the next change. This workflow runs
doctor weekly and keeps one chore: repo-tooling drift issue in step with the
result: it opens the issue when drift appears, rewrites its body while drift
persists, and closes it once doctor is clean. It uses only GITHUB_TOKEN.
name: repo-tooling drift
on:
schedule:
- cron: '17 6 * * 1' # Mondays 06:17 UTC
workflow_dispatch:
permissions:
contents: read
issues: write
jobs:
drift:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: rtorcato/repo-tooling@v6.0.1
id: doctor
with:
fail-on: none # report only; the step below decides about the issue
- name: Open, update or close the drift issue
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
REPORT: ${{ steps.doctor.outputs.json }}
run: |
set -euo pipefail
title='chore: repo-tooling drift'
printf '%s' "$REPORT" > "$RUNNER_TEMP/doctor.json"
count=$(jq '[.results[] | select(.status == "drift" or .status == "missing")] | length' \
"$RUNNER_TEMP/doctor.json")
number=$(gh issue list --state open --search 'repo-tooling drift in:title' \
--json number,title --jq "[.[] | select(.title == \"$title\")][0].number // empty")
if [ "$count" -eq 0 ]; then
if [ -n "$number" ]; then
gh issue close "$number" --comment "doctor is clean as of $(date -u +%F). Closing."
fi
exit 0
fi
{
echo "doctor found $count drift or missing finding(s) on $(date -u +%F)."
echo
jq -r '.results[] | select(.status == "drift" or .status == "missing")
| "- `\(.check)` (\(.status)): \(.detail)"' "$RUNNER_TEMP/doctor.json"
} > "$RUNNER_TEMP/body.md"
if [ -n "$number" ]; then
gh issue edit "$number" --body-file "$RUNNER_TEMP/body.md"
else
gh issue create --title "$title" --body-file "$RUNNER_TEMP/body.md"
fi
The scheduled run is doctor --offline, like every run of the action, so the
GitHub-settings checks (branch protection, repository settings, secrets,
milestones) report skipped. They never open or close this issue. Drift in
those settings needs a manual doctor run with a token that can read them.
Scaffolded workflows
Every scaffold gets a ci.yml (lint / typecheck / test / build) out of the box,
and a library that publishes with semantic-release or Changesets also gets a
release.yml. The Changesets one has its own shape; see
Changesets releases below.
With commitlint on, ci.yml also has a commitlint job. On a push it lints the
commit that landed. On a pull request it lints the PR title as the future
squash commit, <title> (#<number>), so a title that would push the merged
header past 100 characters fails before merge rather than on main (#777). The
workflow adds edited to its pull_request types so a retitled PR is
re-checked, and the title reaches the shell through env:, never ${{ }}
inside run:, because whoever opens the PR controls it.
The release runs only on workflow_dispatch or when a milestone is closed, never
on a plain push to main. One approval then ships a whole batch of merges
(#740). Since #753 it is its own workflow:
- A newer request supersedes a waiting one, never a publishing one
(
concurrency: releaseon thereleasejob). A run still waiting for approval has published nothing, so cancelling it is safe — and CI onmaincan now cancel freely too. An approved run may already be on npm, so cancelling it could leave a version with no GitHub Release (#790). Anin-flightjob checks for one first, and the newer request then queues behind it instead. - It releases the branch's tip. The job checks out the branch when it
starts, i.e. after approval, not the commit that triggered it. A dispatch
releases the branch it was dispatched from, so dispatch from the prerelease
branch (e.g.
gh workflow run release.yml --ref beta) to cut a prerelease. A closed milestone releases the default branch. - It does not re-run CI. install → build → test, then semantic-release.
- To stop a release, reject it at the environment approval. Don't cancel
it: a cancel after approval can land after
semantic-releasehas published, and then the release has happened anyway.
doctor reports a release job still inside ci.yml, a release.yml whose
concurrency does not supersede a waiting run or can cancel a publishing one, or
one that fires on push. fix github-actions migrates
the old layout, carrying the release job's environment: into release.yml.
A job with no environment: gets environment: release, so a fresh
release.yml is always gated (#789).
Re-point the npm trusted publisher's workflow filename to release.yml when you
migrate, or OIDC publishing fails. Beyond that, repo-tooling ships optional deploy
workflows you add on demand — they're too deploy-target-specific to scaffold
by default, so the setup wizard never prompts for them.
Changesets releases
A repo with .changeset/config.json gets a two-job release.yml (#938).
Shipping is merge the Version Packages PR, then one approval:
versionruns on every push tomainwith no environment. It runschangesets/actionwithout a publish script, so it only opens or updates the Version Packages PR. A merge never publishes and never asks for an approval.publishkeepsenvironment: release. It runs only on the push that merged the Version Packages PR (no changesets pending, and a public package's version is not on npm yet) or on aworkflow_dispatch, which retries a failed publish (with changesets pending, the action updates the Version Packages PR instead). It checks out the commit that triggered the run, so a changeset merged while it waits for approval can't turn the publish back into a PR update.- Pre mode works as is. In pre mode (
.changeset/pre.json) the Version Packages PR bumps tox.y.z-beta.N, andchangeset publishpublishes it under the pre tag. publishkeepsconcurrency: release, andversionhas its ownrelease-versiongroup. Both queue runs, never cancel them, and a publish waiting for approval never holds up the next push's Version Packages PR update. There is no milestone trigger: the Version Packages PR is the batch.versioninstalls with--ignore-scripts. It runs ungated on every push withRELEASE_TOKENchecked out, so no dependency install script runs there.
The file name and the environment name stay the same: npm trusted publishing
is bound to release.yml plus the release environment. doctor flags the old
single-job shape (one gated job on dispatch or a closed milestone, so two
approvals per release). fix github-actions rewrites release.yml from the
template and leaves ci.yml alone. Steps only the old job had, such as a
pinned pnpm version, are not carried over, so review the diff with
fix github-actions --diff first.
Moving an existing repo to release.yml
A repo scaffolded before #753 still releases from a job inside ci.yml. Move
it over in this order:
-
Bump
@rtorcato/repo-toolingto a release that contains #775. -
Run
npx @rtorcato/repo-tooling fix github-actions --yes(fix github-actions). It moves your semantic-release job out ofci.ymlintorelease.ymlas is: its steps and step names,env:,environment:,if: failure()steps and comments all come along. It rewrites only what can't work in a workflow of its own:- it deletes the job's
needs:and job-levelif:, since the release triggers replace both; - an
actions/cachestep keyed onneeds.<job>.outputs.*becomespnpm install --frozen-lockfile; - the checkout gets the dispatched-ref
ref:andfetch-depth: 0, keeping its other inputs (such astoken); - a job with no
permissions:getsci.yml's top-level block, andid-token: writeis added for OIDC publishing.
Every other job, trigger and comment in
ci.ymlstays, and aneeds:the move empties is dropped. If the moved job still readsneeds.somewhere (a step using another job's output), it refuses withrelease-job-needs, names each step, and writes nothing. Review the diff before you commit it. Repos that publish with Changesets (changesets/action) or Release Please are skipped:ci.ymlis left alone, anddoctordoes not report them. - it deletes the job's
-
Re-point the npm trusted publisher. On npmjs.com → package → Settings → Trusted Publisher, set the workflow to
release.ymland the environment torelease. Do this in the same sitting as merging step 2. Releases only run when dispatched or when a milestone closes, so there's no window as long as you don't do either in between. -
Move release secrets to the environment. Secrets such as
RELEASE_TOKENgo from repo secrets toreleaseenvironment secrets.doctor'sRelease secretscheck (#754) flags any left at repo level. -
Dispatch the first release with
gh workflow run release.yml --ref mainand approve it. After one successful OIDC publish, you can optionally set npm's Publishing access to "disallow bypass 2fa tokens".
Why ci.yml is generated, not a reusable workflow
The alternative was for consumers to call one shared workflow instead of owning a file:
jobs:
ci:
uses: rtorcato/repo-tooling/.github/workflows/ci.yml@main
One source of truth, upgrades landing automatically. It was rejected:
- It only works on GitHub. repo-tooling also generates GitLab CI, which has no equivalent — so those repos would need the generated file regardless, and the torcato.dev repos would run two different models.
- The consumer stops owning its CI. Adding a job, a matrix entry or a deploy step means either abandoning the shared workflow or growing an input for every knob anyone might want.
- It pins every consumer to a ref of this repo.
@mainruns whatever lands here on their runners; the generated file has no such surface.
The one thing it was meant to solve — a generated ci.yml drifting from the
preset with nobody noticing — is now covered by the audit instead. doctor
compares the workflow's action pins against the preset and reports the
disagreement, fix github-actions --diff shows the delta before anything is
overwritten, and the composite action above turns that into a CI gate. Drift is
visible and reconcilable, which was the only real gap in owning the file.
Optional deploy workflows
Add any of these to an existing repo with fix:
npx @rtorcato/repo-tooling fix docker-publish
npx @rtorcato/repo-tooling fix vercel-deploy
npx @rtorcato/repo-tooling fix cloudflare-pages
npx @rtorcato/repo-tooling fix preview-deployments
Each is safe-add — it writes .github/workflows/<name>.yml only if that
file doesn't already exist, so it never clobbers a workflow you've customized.
| Target | Workflow | Trigger | Secrets |
|---|---|---|---|
docker-publish | Build + push a Docker image to GHCR | tag push (v*) | none (uses GITHUB_TOKEN) |
vercel-deploy | Preview deploy to Vercel, then production behind the production environment | push to main | VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID |
cloudflare-pages | Preview deploy of a static build to Cloudflare Pages, then production behind the production environment | push to main | CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID |
preview-deployments | Per-PR preview deploy + URL comment | pull_request | VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID |
Each workflow ships with least-privilege permissions: and references its
secrets via ${{ secrets.* }} — add them under Settings → Secrets and
variables → Actions in your repo. A couple carry a placeholder to fill in
(the Cloudflare Pages --project-name, for example).
Production waits for an approval
vercel-deploy and cloudflare-pages deploy in two jobs (#848). Every push to
main gets a preview deploy straight away. The production job runs in the
production GitHub environment, so it sits waiting until a required reviewer
approves it, the same gate the npm release environment puts on a publish.
There is no long-lived prod branch to drift from main. A newer push that is
still waiting replaces an older waiting one, and a deploy already running is
never cancelled. A workflow_dispatch from any branch other than main gets
the preview only.
The approval gates the production deploy only: the preview job holds the same
deploy tokens and runs unreviewed on every push to main.
GitHub creates a missing environment the first time a job uses it, with no
protection, so the first production deploy would go out unreviewed. Create the
environment before the workflow's first run, with yourself as the required
reviewer, and limit it to main. Then a workflow_dispatch from another branch
whose copy of the workflow drops the main guard still can't reach it:
echo "{\"reviewers\":[{\"type\":\"User\",\"id\":$(gh api user --jq .id)}],\"deployment_branch_policy\":{\"protected_branches\":false,\"custom_branch_policies\":true}}" \
| gh api -X PUT "repos/{owner}/{repo}/environments/production" --input -
gh api -X POST "repos/{owner}/{repo}/environments/production/deployment-branch-policies" \
-f name=main -f type=branch
Or do it by hand under Settings → Environments → New environment →
production: add yourself under Required reviewers, and under
Deployment branches and tags pick Selected branches and tags and add
main. Add other reviewers there too.
vercel-deploy and preview-deployments pin the Vercel CLI to an exact
version, since it runs with VERCEL_TOKEN in scope. Dependabot can't bump a
version inside a run: line, so bump the pin by hand.