Skip to content
hushrunDocs

Quickstart

npx hushrun init sets hushrun up in a repository in about three minutes. It wraps your checks, signs you in, lets your CI share results with no secret, and shows every change before it makes it.

Before you start

  • A git repository with a package.json at its root whose scripts run your checks: test, lint, typecheck and the like. Without one, see By hand.
  • Node.js, for npx.
  • A GitHub or Google account to sign in with.
  • Optional: the GitHub CLI, gh, signed in. While you sign in, init uses it to count how often CI ran again on code it had already passed in the last 30 days.

Run init

At the repository's root:

npx hushrun init

npx asks to install the hushrun package the first time. init then looks at the repository, opens your browser to sign in, and lists what it will change. --dry-run shows the same list without signing in or changing anything:

$ npx hushrun init --dry-run
…
hushrun init will change:
  package.json
    "lint": "eslint ." → "hushrun run -- eslint ."
    "test": "vitest" → "hushrun run -- vitest run" (vitest alone watches on a terminal)
    "typecheck": "tsc --noEmit" → "hushrun run -- tsc --noEmit"
    "hushrun": {"backend": "<your org's URL, once you sign in>"}, where CI, teammates and agents share results
    devDependencies: "hushrun": "^0.1.0"
  .github/workflows/ci.yml
    job test: adds permissions contents: read and id-token: write. The job's token then has only these two: add any other it needs
  your org
    connects github.com/acme/shop, so that its CI records results with its own ID token
    adds github.com/acme/shop to your org, for promoting its builds, unless it is there already
  hushrun.yaml
    a new file: repository github.com/acme/shop, the URL the org gives it, and its log key

Nothing changed (--dry-run).

Without --dry-run, it signs you in first, so the list names your organization and its URL, and it ends with Apply? [Y/n].

Approve the sign-in

init prints a code and opens a page where you approve it. Pick the organization the repository belongs to. With no organization yet, you create one on that page, or join one you were invited to. If the repository already belongs to an organization you aren't in, init offers to ask its admins to let you in.

Signing in saves a token that only you can read, and registers this machine with your organization; hushrun logout revokes both. To sign in from a terminal with no browser, add --no-browser: init prints the page's address instead of opening it.

What init changes

Once you agree, init makes exactly the changes it listed and keeps every other byte of each file as it was:

  • Your checks' scripts get hushrun run -- in front. Each check takes its script's name. A bare vitest, which watches at a terminal, becomes vitest run. Scripts that watch, serve, fix or write files, or that use shell operators such as || or ;, stay as they are, and init says why.
  • "hushrun": {"backend": …} in package.json names your organization's URL on hushrun. Committed with the code, it tells CI, your teammates and their agents where results go, with no variable to set.
  • hushrun joins devDependencies, installed with your package manager (npm, pnpm, Yarn or Bun), so npm ci installs hushrun in CI too.
  • GitHub Actions jobs that run a wrapped check get id-token: write, so CI records results with its own short-lived token. There is no secret to store.
  • Your organization connects the repository, so its CI may record results.
  • hushrun.yaml, a small file for promotion, names the repository and its URL on hushrun. init writes it when an admin or owner of the organization runs it, since that adds the repository to the dashboard. Skipping checks doesn't need it.

Then init runs one wrapped check twice, through your package manager, to show the skip:

$ npm run lint

> shop@1.0.0 lint
> hushrun run -- eslint .

hushrun: lint running: no pass yet for this exact code
hushrun: lint passed in 0.2s; it won't run again on this code
$ npm run lint

> shop@1.0.0 lint
> hushrun run -- eslint .

hushrun: lint skipped: this exact code passed just now (saves 0.2s)

Commit and push

Review the changes with git diff, then commit and push them. CI records its first results, and from then on skips any check this exact code already passed, wherever it passed: on a laptop, in CI or in an agent's sandbox. In the dashboard, at https://app.hushrun.com, the repository's page lists its checks: each one's newest run, its skips and the time they saved, and which checks are flaky.

Teammates get hushrun with the commit. Until one of them signs in, their checks run as usual, and at a terminal hushrun ends with:

hushrun: sign in to share results with acme: npx hushrun login

With a coding agent

A coding agent can run init for you. Give it this prompt, word for word:

Add hushrun to this repository. Run `npx hushrun init --yes` at the repository root; it prints a sign-in link, which I'll approve in my browser. Then show me the diff it made, run the checks it wrapped once, and commit the change on a new branch.

--yes applies the changes without asking. The agent shows you the sign-in link, and you approve it in your browser. For coding agents has the rest of what an agent should know.

By hand

hushrun doesn't need package.json or init. Install it with npm:

npm install --global hushrun

Then put hushrun run NAME -- in front of any check, in any language:

hushrun run unit -- cargo test
hushrun run lint -- golangci-lint run

unit names the check, and everything after -- is its command. Results stay on your machine until you sign in with hushrun login, or until a backend is named, as Where results go explains. Without a global install, npx hushrun run unit -- cargo test works the same way.

Next

Markdown