| name | toolr-ci-setup |
| description | Wire the `s0undt3ch/ToolR` GitHub Action into a caller
repository's workflows. Use when setting up toolr in CI;
when authoring `.github/workflows/*.yml` that runs a toolr
command; when wiring `toolr self build-manifest --check`
as a CI gate for a plugin repository; when picking the
right pin form for `uses: s0undt3ch/ToolR@…`; when forcing an
in-tree `tools/.venv` in CI via `TOOLR_VENV_LOCATION`; or when
debugging the action's minimum-version error, attestation
verify failures, or persistent venv cache misses. Triggers
on phrases like "set up toolr in CI", "GitHub Actions for
toolr", "use the toolr action", "cache toolr in CI",
"in-tree venv in CI", "verify SLSA attestation in CI", and
literal `uses: s0undt3ch/ToolR@` snippets. Stays inert on local
authoring requests (covered by the `toolr-command-authoring`
skill), on wheel-building outside a CI gate (covered by
`toolr-command-packaging`), and on toolr's own internal
`.github/actions/*` sub-actions.
|
Setting up toolr in GitHub Actions
You are wiring the s0undt3ch/ToolR composite action into a
repository's CI. The action installs the toolr Rust binary, verifies
its SLSA build provenance, caches the binary and the per-repo
tools/.venv, and hands the next workflow step a toolr on PATH.
Your job is to produce (or modify) a .github/workflows/*.yml that
consumes the action correctly.
This skill teaches the consumer side of the action. The
authoritative input/output surface lives in
references/action.md, regenerated from
action.yml on every release — read it when you need exact defaults
or argument shapes.
What this skill covers
- Pinning
uses: s0undt3ch/ToolR@<sha> correctly.
- A minimal one-step workflow that runs a toolr command.
- The two canonical recipes: running a toolr command in CI, and
gating
toolr self build-manifest --check for plugin repos.
- The three failure modes a typical caller hits first.
What this skill does not cover
- Authoring or editing the
tools/*.py commands the workflow runs —
see the
toolr-command-authoring
skill.
- Building or shipping a toolr plugin wheel — see the
toolr-command-packaging
skill. This skill only covers the CI gate side
(--check), not manifest generation itself.
- Non-action install paths in CI (manual
curl | sh fallback,
mise-action, self-hosted runner image baking). Use the action.
- Toolr's own internal
.github/actions/* sub-actions
(apply-release-patch, configure-git, setup-pre-commit,
setup-virtualenv, throttle). Those are toolr's release
plumbing, not a public consumer surface — do not call them from
external repos.
The minimum viable workflow
name: toolr
on: [push, pull_request]
jobs:
run:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: s0undt3ch/ToolR@<sha>
- run: toolr <group> <cmd>
Replace <sha> with the full commit SHA of the release tag and
<group> <cmd> with the toolr command you want to run. That is
the whole surface for the common case — the action handles
attestation verification, caching, and venv setup.
Pinning policy
Recommended default — SHA-pinned with a version comment:
- uses: s0undt3ch/ToolR@a1b2c3d4e5f6...
This is the form GitHub's own security guidance recommends and the
form toolr itself uses for upstream actions (see actions/cache in
action.yml). The version comment lets a human reader (and
Dependabot) match the SHA to a release tag without resolving the ref.
Acceptable for prototypes — tag-pinned:
- uses: s0undt3ch/ToolR@v0.20.0
Easier to write while iterating; trade reproducibility for readability.
Do not use floating-major (@v0) pre-1.0. Toolr's pre-1.0
contract permits breaking changes on minor bumps, so @v0 is
effectively latest and may silently break a workflow.
The action enforces a minimum version of 0.20.0 (the first
binary-only release shape). Anything below that fails fast with a
clear error.
Recipe 1 — Run a toolr command in CI
Single-OS form was shown above. For multi-OS coverage (use this when
your toolr commands shell out to platform-specific tooling or you
ship a plugin that must work cross-platform):
name: toolr
on: [push, pull_request]
jobs:
run:
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/checkout@v4
- uses: s0undt3ch/ToolR@<sha>
- run: toolr <group> <cmd>
The action ships binaries for x86_64/aarch64 Linux (glibc and
musl), x86_64/aarch64 macOS, and x86_64 Windows. The right
archive is selected automatically from RUNNER_OS + uname -m.
For the authoring side — how the tools/<file>.py defining the
command you're running is structured — see
toolr-command-authoring.
Recipe 2 — Gate plugin manifests with --check
When you ship toolr commands as a plugin wheel, the committed
toolr-manifest.json must match what toolr self build-manifest
would produce from the current source. The --check flag gives you
a non-zero exit on drift. Wire it as a CI gate so a stale manifest
cannot land:
name: toolr-manifest
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: s0undt3ch/ToolR@<sha>
- run: |
toolr self build-manifest \
--source-dir src/my_plugin \
--package my_plugin \
--check
Replace src/my_plugin with your plugin source directory and
my_plugin with the importable package name.
For the generation side — how to produce toolr-manifest.json
in the first place, what schema it follows, and how to include it
in the wheel — see
toolr-command-packaging —
this skill only owns the --check gate side.
Inputs and outputs at a glance
The full input/output surface (defaults, descriptions, what each
input controls) lives in
references/action.md. It is regenerated
from action.yml on every release, so it cannot drift. Read it when
you need to override caching, point at a different release, or pass
extra uv sync flags.
Where the venv lives in CI
Locally, toolr materialises the tools venv in a per-repo cache
directory by default ($XDG_CACHE_HOME/toolr/<repo-key>/venv/). That
path is volatile on CI runners, so the action exports
TOOLR_VENV_LOCATION=in-tree for you, which forces the venv to
tools/.venv/ inside the checkout regardless of what
[tool.toolr] venv-location says in your tools/pyproject.toml. That
stable, in-checkout path is exactly what the tools/.venv cache
(see cache-tools-venv) keys on.
-
Using the action? Do nothing — it sets the env var itself.
-
Running toolr in CI without the action (a bare run: step,
which this skill otherwise discourages)? Export it yourself so the
venv lands somewhere cacheable:
- run: toolr <group> <cmd>
env:
TOOLR_VENV_LOCATION: in-tree
TOOLR_VENV_LOCATION accepts in-tree or cache; a typo is a hard
error rather than a silent fallback. See the venv-location
reference
for the file-configured equivalent.
Common failure modes
refusing to install toolr <ver> — minimum supported version is 0.20.0 — the action enforces a 0.20.0 floor because earlier
releases shipped as a Python package and are no longer compatible.
Upgrade your pin to 0.20.0 or later; do not try to work around
the check.gh attestation verify fails on a fork — the action verifies
the SLSA build provenance of every downloaded archive. On runners
without gh available, set skip-attestation: true only if you
understand you are turning off the supply-chain gate. Prefer
installing gh (it's already present on GitHub-hosted runners) or
pre-baking it into self-hosted runner images.tools/.venv cache misses every run — the venv cache key
hashes tools/pyproject.toml, tools/uv.lock, and uv.lock. If
none of those are committed (or if your tools/ layout is
non-standard), the key never stabilises. Commit the lock files
alongside tools/pyproject.toml. Local complement to the CI gate:
the --check recipe above works equally well as a prek hook in
your pre-commit config.
Authoring and packaging are different problems
If you haven't written the toolr commands yet, this skill cannot
help you produce them. Invoke
toolr-command-authoring
to write them, then come back here to wire the workflow. For
shipping commands as a distributable plugin, see
toolr-command-packaging —
this skill only owns the --check gate side.
