# Roll out to your team This guide is for the admin who brings hushrun to a team. It starts with which credential each part uses, then sets everything up in order. To estimate what hushrun saves and which plan you need first, see [Estimate savings and cost](https://hushrun.com/docs/savings.md). ## Which credential each one uses Whoever records a result needs a credential, so the server knows who recorded it. Two terms first: - An **ID token** is a credential GitHub signs for a job. It names the job's repository, so GitHub Actions needs no secret. - An **agent token** lets something without a browser record as `agent:`. Its machine key signs what it records. | Who runs checks | Credential | Where it's set | Who makes it | |---|---|---|---| | A person's laptop | Their sign-in, through `npx hushrun init` or `npx hushrun login` | `credentials.json`, in hushrun's configuration directory | The person, once | | A coding agent on a laptop | The person's sign-in | Nothing to set | The person, as above | | GitHub Actions | The job's ID token | `id-token: write` in the job's `permissions` | `npx hushrun init` adds it | | Other CI | An agent token and its machine key | `HUSHRUN_TOKEN` and `HUSHRUN_MACHINE_KEY`, as CI secrets | An admin, with `hushrun token create --agent ` or the dashboard's **Agents** page | | An agent sandbox | `HUSHRUN_AGENT`, one string that holds an agent token and its key | The sandbox's environment | An admin, the same way | Without a credential, checks still run, but nothing is shared. When several are set, [Where results go](https://hushrun.com/docs/results.md#credentials) says which one wins. ## Create your organization Sign up at https://app.hushrun.com/sign-up with **Continue with GitHub**. Your first sign-up makes an organization named after you, with you as its owner. Or start from a terminal: the sign-in page that `npx hushrun init` opens lets you name one. More in [Organizations](https://hushrun.com/docs/teams.md#organizations). ## Set up each repository At the root of each repository, run init, then commit and merge the change it makes: ```bash npx hushrun init ``` init wraps the checks your scripts and CI run, names your organization's backend, and adds `id-token: write` to the GitHub Actions jobs that need it ([every change](https://hushrun.com/docs/reference/cli.md#hushrun-init)). Run it as an admin or owner, which also gives the repository its own page in the dashboard ([Repositories](https://hushrun.com/docs/teams.md#repositories)). If you belong to several organizations, `--org ` picks one. ## Invite people On the dashboard's **Members** page, invite each person by email address or GitHub login, with a [role](https://hushrun.com/docs/teams.md#roles). hushrun sends no invitation email, so tell them. Each person then signs in once, in a clone of the repository: ```bash npx hushrun login ``` Their coding agents on that laptop use the same sign-in. People can also [ask to join](https://hushrun.com/docs/teams.md#requests). ## Tell your team what changes For people, little changes: - They run checks as before, through the same scripts. A check this exact code already passed skips; `--force` runs it anyway ([Run a check again](https://hushrun.com/docs/daily.md#run-again)). - Before a push, `npx hushrun ready` lists what CI would still run, and the pre-push hook warns about the same. Their push goes on. - With Bun, they run `bun run test`, not `bun test`, which hushrun never sees. [Day to day](https://hushrun.com/docs/daily.md) is the page to send them. Coding agents need no briefing: init adds instructions for them, and the pre-push hook refuses an agent's push until the checks that can run on its machine pass ([For coding agents](https://hushrun.com/docs/for-agents.md)). If your CI runs on `pull_request`, add one line to their instructions: bring the branch up to date with its base before running the checks. Otherwise CI sees new files and runs every check whose files changed ([Pull requests](https://hushrun.com/docs/ci.md#pull-requests)). ## Set up CI - **GitHub Actions** needs nothing more. Once init's change is merged, each job records with its ID token. - **Other CI**, such as GitLab CI, CircleCI or Jenkins, records with an agent token and its machine key. Create them in the repository, signed in with `hushrun login`: ```bash hushrun token create --agent gitlab-ci --expires 365d ``` Store them as CI secrets named `HUSHRUN_TOKEN` and `HUSHRUN_MACHINE_KEY`. Without the key, checks run but nothing is recorded. [Set up CI](https://hushrun.com/docs/ci.md) has the details. ## Give sandboxes a token Coding agents in sandboxes, such as Claude Code cloud sessions, have no browser to sign in with. Create an agent token, and give each sandbox one variable, `HUSHRUN_AGENT`. One token can serve a whole fleet. ```bash hushrun token create --agent fleet-a ``` At a terminal, its first line is `HUSHRUN_AGENT=`, shown once. [Agents in sandboxes](https://hushrun.com/docs/agents.md#sandboxes) has the steps. ## Decide how far CI trusts others By default, a pass from a member's laptop or one of your organization's agents skips the same check in a CI job without variants, on the same files. So CI doesn't repeat what someone already ran. In a team whose agents push often, that can be most of what hushrun saves in CI. Only a member's signed-in machine, one of your organization's agent tokens or the repository's own GitHub Actions can record a pass that others skip on. A signature proves who recorded a result, not that the check really ran ([Who can record a pass](https://hushrun.com/docs/run.md#who-can-record)). hushrun compares only the files, the check's name, its exact command, its directory and any `counts_from` rule. A check that depends on anything else, such as an environment variable or a tool version, can skip when it shouldn't ([When a skip can be wrong](https://hushrun.com/docs/run.md#limits)). For such checks, pick a guard: - **Name each variant.** Give a check that runs on several systems or versions a name for each ([Jobs and variants](https://hushrun.com/docs/ci.md#variants)). - **Say where it counts.** `counts_from` in `hushrun.yaml` names what the check needs, such as Linux or a Go version. A run anywhere else leaves no pass ([Where a check counts](https://hushrun.com/docs/where-a-check-counts.md)). - **Make CI reuse only CI's results.** Turn it on under **CI rules** on a repository's **Settings**. CI then skips only on CI's passes, while people and agents still skip on everyone's ([details](https://hushrun.com/docs/ci.md#ci-only)). > **Note:** The CI-only setting covers GitHub Actions. On GitLab it works differently: see [CI reuses only CI's results](https://hushrun.com/docs/ci.md#ci-only). ## Watch usage Each plan includes a number of recorded checks a month: the passes and fails hushrun records. Skips and reads are free. At the limit, checks still run. On Free and Pro, new results aren't recorded until the next period. Team and Growth keep recording as overage, up to the spend cap ([At the limit](https://hushrun.com/docs/plans.md#at-the-limit)). To see where you stand, open **Usage** in the dashboard, or run: ```bash hushrun repository usage ``` Owners and admins get an email at 80% and 100% of the included checks. [Plans and limits](https://hushrun.com/docs/plans.md) has the prices and what counts. [Measure it in a trial](https://hushrun.com/docs/savings.md#measure) shows where to read the time saved. ## Next - [Set up CI](https://hushrun.com/docs/ci.md): GitHub Actions, variants and other CI. - [Agents in sandboxes](https://hushrun.com/docs/agents.md#sandboxes): one variable per sandbox. - [Organizations](https://hushrun.com/docs/teams.md): roles, machines and tokens in the dashboard. - [Security and data](https://hushrun.com/docs/security.md): what hushrun keeps, where, and for how long. - [How it works](https://hushrun.com/docs/run.md): what hushrun compares, and when a skip can be wrong.