Skip to main content

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​

InputDefaultWhat it does
directory.Directory to diagnose, relative to the workspace.
fail-ondriftdrift 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​

OutputWhat it is
jsonThe 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.1 runs CLI 5.4.1. The git ref is the only pin, and Dependabot's github-actions ecosystem 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-node internally 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: doctor is a read-only file audit already published as an npm CLI, so a container would only add an image to build, publish and pull.
  • doctor never 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: release on the release job). A run still waiting for approval has published nothing, so cancelling it is safe — and CI on main can now cancel freely too. An approved run may already be on npm, so cancelling it could leave a version with no GitHub Release (#790). An in-flight job 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-release has 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:

  • version runs on every push to main with no environment. It runs changesets/action without a publish script, so it only opens or updates the Version Packages PR. A merge never publishes and never asks for an approval.
  • publish keeps environment: 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 a workflow_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 to x.y.z-beta.N, and changeset publish publishes it under the pre tag.
  • publish keeps concurrency: release, and version has its own release-version group. 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.
  • version installs with --ignore-scripts. It runs ungated on every push with RELEASE_TOKEN checked 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:

  1. Bump @rtorcato/repo-tooling to a release that contains #775.

  2. Run npx @rtorcato/repo-tooling fix github-actions --yes (fix github-actions). It moves your semantic-release job out of ci.yml into release.yml as 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-level if:, since the release triggers replace both;
    • an actions/cache step keyed on needs.<job>.outputs.* becomes pnpm install --frozen-lockfile;
    • the checkout gets the dispatched-ref ref: and fetch-depth: 0, keeping its other inputs (such as token);
    • a job with no permissions: gets ci.yml's top-level block, and id-token: write is added for OIDC publishing.

    Every other job, trigger and comment in ci.yml stays, and a needs: the move empties is dropped. If the moved job still reads needs. somewhere (a step using another job's output), it refuses with release-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.yml is left alone, and doctor does not report them.

  3. Re-point the npm trusted publisher. On npmjs.com → package → Settings → Trusted Publisher, set the workflow to release.yml and the environment to release. 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.

  4. Move release secrets to the environment. Secrets such as RELEASE_TOKEN go from repo secrets to release environment secrets. doctor's Release secrets check (#754) flags any left at repo level.

  5. Dispatch the first release with gh workflow run release.yml --ref main and 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. @main runs 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.

TargetWorkflowTriggerSecrets
docker-publishBuild + push a Docker image to GHCRtag push (v*)none (uses GITHUB_TOKEN)
vercel-deployPreview deploy to Vercel, then production behind the production environmentpush to mainVERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID
cloudflare-pagesPreview deploy of a static build to Cloudflare Pages, then production behind the production environmentpush to mainCLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
preview-deploymentsPer-PR preview deploy + URL commentpull_requestVERCEL_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.