Reusable GitHub Actions workflows for the repositories of klconsultancy. A repository calls one with a short workflow of its own; the logic, the pinned actions and the permissions live here, once.
| Workflow | What it does |
|---|---|
claude-review.yml |
Claude reviews every pull request against the repository's own CLAUDE.md / AGENTS.md |
pr-title.yml |
A pull request's title is a Conventional Commit, the squash commit's message |
zizmor.yml |
zizmor audits the repository's own workflows, at a version pinned here |
python-uv.yml |
ruff, mypy, pytest (a Python matrix) and a checked build, for a uv project |
home-assistant.yml |
hassfest and HACS validation of a Home Assistant custom integration |
shell.yml |
shellcheck, zsh -n, gitleaks and bats, for scripts and dotfiles |
renovate.yml |
Renovate as a GitHub App, its version pinned once for every repository |
release-please.yml |
release-please as a GitHub App, plus a pre-release for a release-candidate tag |
The repository is public, so repositories outside the organization (a personal account's, private ones too) can call these workflows as well. Each workflow's header holds its caller and its inputs.
On every pull request that is opened, updated, reopened or marked ready, Claude reviews the
change with claude-code-action and this
workflow's own prompt:
- It reviews against the calling repository's rules: every
CLAUDE.mdandAGENTS.md, the files they import with@, and theguidelinesinput. The rules come from the base branch: a pull request cannot change the rules it is reviewed against. A change to a rules file is itself reviewed, and named in the summary. - Every push is reviewed. After the first review, only what changed since the last successful review (changes merged in from the base left out). A force-push or a base merge that resolved conflicts gets a full review again.
- It posts inline comments, and one summary comment per push: the scope, the files it read, what it skipped, and the rules that applied. A clean review is one line.
- The check is red when Claude ended without a summary: a green check means a review.
Expect red on a pull request that adds or changes the caller workflow file: the Claude
GitHub App only grants its token for a caller identical to the default branch's, and it
compares a reusable workflow the caller takes from its own repository the same way. So a
pull request here that changes
claude-review.ymlis red too ("Workflow validation failed", #9): such a change is tested only after the merge, in a caller. - It never approves. A person reads the comments and merges.
- Its tools are a strict list: reading files, inline comments,
gh pr view,gh pr diffandgh pr comment. Anything else is denied (--permission-mode default, not the action's auto mode, whose safety review can pass a call no rule allows): a review reads untrusted pull request content, so that content must not be able to make it run commands. - A new push cancels the review still running for the same pull request; the next review then covers both pushes.
Shell scripts in .github/claude-review/ decide the scope and put
the base rules in place before Claude starts; test/ holds their tests
(bats test/).
Skipped: drafts, pull requests opened by bots (Renovate, release-please; the action refuses bot actors anyway) and pull requests from forks (GitHub withholds the secret from those).
| Input | Default | What it does |
|---|---|---|
model |
claude-opus-5-5 |
The Claude model that reviews. |
max-turns |
40 |
Cap on Claude's turns per review. |
timeout-minutes |
20 |
Cap on the job's run time. |
guidelines |
"" |
More guideline files to review against, space-separated paths without quotes (e.g. docs/design/README.md). CLAUDE.md, AGENTS.md and the files they import with @ are always read; a file they only link to is not. |
show-full-output |
false |
Prints Claude's full transcript, tool results included, in the job log, to see what a review read and why. Private repositories only, and only for a while: the log holds whatever Claude read. |
- Install the Claude GitHub App on all repositories.
- Run
claude setup-tokenand store the token as the organization Actions secretCLAUDE_CODE_OAUTH_TOKEN. Reviews then run on that Claude subscription. If the GitHub plan does not share organization secrets with private repositories, set the secret on those repositories instead.
Add .github/workflows/claude-review.yml:
name: Claude review
on:
pull_request:
types: [opened, synchronize, ready_for_review, reopened]
permissions: {}
jobs:
review:
name: Review
permissions:
actions: read # find the last successful review
contents: read
pull-requests: read
issues: read
id-token: write # the action authenticates as the Claude GitHub App
uses: klconsultancy/workflows/.github/workflows/claude-review.yml@<sha> # v1.0.0
secrets:
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}- Pin a release:
<sha>is the commit of its tag, and the comment its version (see Releases). Renovate (helpers:pinGitHubActionDigests) moves both together. - The job's permissions are the most the reusable workflow gets: keep them as above.
- Pass the secret by name, not with
secrets: inherit, so the repository hands over only this one. - Give the repository a
CLAUDE.mdwith its rules: the review is only as specific as that.
Inputs (see the table above) go under with::
with:
max-turns: 60Checks the pull request's title with
action-semantic-pull-request, so
the squash commit is a Conventional Commit. It runs on pull_request, not
pull_request_target: it only reads the title, which a read-only token can, and the pull
request that adds the caller gets the check too.
Add .github/workflows/pr-title.yml:
name: PR title
on:
pull_request:
types: [opened, edited, synchronize, reopened]
merge_group: # only with a merge queue
permissions: {}
jobs:
title:
name: PR title
permissions:
pull-requests: read
uses: klconsultancy/workflows/.github/workflows/pr-title.yml@<sha> # v1.0.0The required status check in the repository's ruleset is PR title / Conventional commit title: a job from a reusable workflow is named <caller job> / <its own job>. With a
merge queue, a required check must also report on the queue's merge group, so the caller
adds merge_group. There the check passes without checking: the group has no title, and the
pull request's title was checked before it entered the queue.
zizmor.yml audits the calling repository's workflows with
zizmor, at the version pinned here. Inputs: paths
(default .github/), config (the repository's .github/zizmor.yml), version,
runs-on, and container for a runner without Python (Python and pip are installed in
it). This repository runs it on itself from test.yml, so a pull request here runs the
changed workflow before any caller moves its pin.
A repository's single required check (e.g. CI success) stays a job of its own that
needs: the calls: a reusable workflow's jobs report as <caller job> / <job>.
python-uv.yml runs ruff, mypy and pytest through
uv run against the locked environment, so the tools are the project's own. Inputs:
python-version, test-python-versions (a JSON array), mypy, build (uv build and
twine check; needs a release dependency group with twine) and check-uv-pins (the uv
version agrees in .devcontainer/Dockerfile, pyproject.toml and
.pre-commit-config.yaml). Jobs particular to one project (a dependency's
lowest or newest version) stay in its CI, next to the call.
home-assistant.yml runs hassfest and the HACS
action on a custom integration. Inputs: hacs-category (default integration) and
hacs-ignore. Both validate against rules that change without a commit in the calling
repository, so callers also run it on a weekly schedule.
shell.yml checks scripts and dotfiles: shellcheck, zsh -n,
gitleaks over the history and optionally bats. Inputs: shellcheck-pathspec,
zsh-pathspec, gitleaks, bats, bats-path. gitleaks needs the secret
GITLEAKS_LICENSE in a repository of an organization; a personal account's repositories
need none.
renovate.yml runs Renovate as the GitHub App
klconsultancy-renovate-bot, at the version pinned here. Inputs: app-client-id
(vars.RENOVATE_APP_CLIENT_ID), runs-on, renovate-image and renovate-version; the
secret RENOVATE_APP_PRIVATE_KEY. The schedule is the caller's.
Extend the preset shared-workflows.json:
{
"extends": ["config:recommended", "helpers:pinGitHubActionDigests", "github>klconsultancy/workflows:shared-workflows"]
}The pin on this repository then moves in a pull request of its own, "shared workflows",
with the release notes in it, which waits for review, also where the repository automerges
the rest (a major release, a breaking change, comes in one of its own):
release-please.yml and renovate.yml only run on main, and claude-review.yml skips
pull requests opened by a bot, so no check of the pull request runs a change to them, and a
broken one would land everywhere at once.
- Automerge after all, for a repository whose checks run every workflow it calls (no
release-please, no Renovate, no Claude review): a rule of its own, after the preset's:
{"matchPackageNames": ["klconsultancy/workflows"], "automerge": true}. - A rule that groups all actions (
"matchManagers": ["github-actions"]with agroupName) must leave the pin out with"matchPackageNames": ["!klconsultancy/workflows"]: the repository's rules come after the preset's, and would pull the pin back into that group, which would then wait for review with it.
release-please.yml runs release-please as the
GitHub App klconsultancy-release-bot, so its release pull requests and tags start
workflows. Inputs: app-client-id (vars.RELEASE_APP_CLIENT_ID), create-prerelease,
assets-command and assets;
the secret RELEASE_APP_PRIVATE_KEY.
-
It outputs
release_createdandtag_name, for the caller's own release jobs (PyPI, binaries, images):needs: releaseandif: needs.release.outputs.release_created == 'true'. -
Release candidates: a repository has them when its caller also triggers on tags such as
v1.2.3-rc.1. Every such tag is checked: release-please's open release pull request is for 1.2.3, and the tagged commit is on that pull request's base branch. Then the outputrelease_candidateis'true'; otherwise the check fails, and nothing of the tag is built or released (the tag is left for a person to delete). Who creates the pre-release:create-prerelease: true: this workflow, at once (an integration HACS installs, withassetsif it needs files);- off: the repository, after its own build (PyPI, binaries, images), in a job with
if: needs.release.outputs.release_candidate == 'true'.
-
With
assets(paths or globs, one per line) andassets-command, the release gets files of its own, such as the zip HACS installs: the command builds them in a checkout of the tag, with the tag in$TAG, and they are attached to the release, and to a release candidate's pre-release withcreate-prerelease: true. The command runs without a token (the checkout uses a read-only one); a separate job uploads, as the app, retries and checks that every file is there. The caller grants nothing more. -
Immutable releases take no assets once published, so a release with assets is a draft until its assets are attached; the job Publish release then publishes it (and keeps "Latest" on the highest version). A release candidate's pre-release is a draft here already. For release-please's own releases the caller's
release-please-config.jsonsets, per package:"draft": true, "force-tag-creation": true
force-tag-creationbecause GitHub tags a draft only when it is published, and release-please needs the tag to find the previous release. A draft whose assets fail stays a draft: fix the cause and re-run the failed jobs. Withoutassetsthis workflow publishes no draft: a repository that attaches files of its own (binaries, images) in a job after it, with"draft": true, publishes its draft itself, and decides "Latest" itself too: a published draft becomes Latest unless told otherwise, so on a maintenance branch it passes--latest=falsewhen a higher release exists (gh release edit "$TAG" --draft=false --latest=false), as Publish release does after itssort -Vcheck. -
Maintenance branches: release-please works on the branch that was pushed. A caller that also triggers on a branch such as
1.x(push: branches: [main, "1.x"]) gets release pull requests against1.x, its own changelog there, andv1.x.yreleases next to main's. Such a release does not take GitHub's "Latest" from a higher version: when the release that was latest before it is the higher one, that one is made latest again.
What is deliberately not here: OpenSSF Scorecard (with publish_results the scorecard job
must be in the repository's own workflow file, with only approved steps) and the PyPI
upload (PyPI's trusted publishing does not accept a reusable workflow as the publisher).
Both stay in each repository.
Every change goes through a pull request. Pin actions to a full commit SHA with the version
in a comment, keep permissions minimal and persist-credentials: false, and check the
file with actionlint and
zizmor; the Test workflow runs actionlint, zizmor,
shellcheck and the bats tests on every pull request, and claude-review-check.yml reviews the pull
request with this repository's Claude review workflow (main's: a pull request that changes
it gets no review, see above). Callers only pick a change up when their pin moves to a
release that has it.
This repository releases with release-please, through its own release-please.yml
(release.yml), like the repositories that call it:
merging the release pull request tags vX.Y.Z and creates the GitHub release with the
changelog. Callers pin those releases, @<sha> # v1.2.3: a tag doesn't move (a ruleset
keeps v* tags from being moved or deleted; only the release app creates them), so the
comment stays true for zizmor's ref-version-mismatch, and Renovate moves the SHA and the
version together.
The pull request's title decides the version, so it says what a caller notices:
fix:a patch,feat:a minor;!(feat!:) a major: a caller must change something (an input renamed or removed, a new required permission or secret). Renovate brings a major in a pull request of its own;ci:,docs:,test:,chore:release nothing: they change this repository only.
The check Release type (release-type.yml) holds
a pull request to that: one that changes a reusable workflow (a file with workflow_call:)
or the scripts claude-review.yml runs (.github/claude-review/) fails under a title that
releases nothing, since callers would never get the change. The Renovate preset
shared-workflows.json is the exception: Renovate reads it from main, so a change to it
takes effect at once, whatever the title.
Renovate runs on this repository too (renovate-run.yml, through renovate.yml itself,
with renovate.json): it keeps the pins every caller shares current, the
actions as well as the Renovate and zizmor versions in the inputs' defaults. Those updates
are fix(deps):, a patch release each, and wait for review: once released, they reach
every caller with its next pin update.