# Your team on hushrun An organization on hushrun's hosted service holds your team's repositories, the check results its members, agents and CI record, and who may change what, all in the dashboard at https://app.hushrun.com. ## Sign up Go to https://app.hushrun.com/sign-up and choose **Continue with GitHub** or **Continue with Google**. You can connect the other one later from **Account**, in the user menu at the bottom of the sidebar. The account you connect doesn't need the same email. ### Which accounts are one person A person on hushrun has at most one GitHub account and one Google account. A sign-in finds its person in this order: 1. An account already connected signs in as its person. 2. Otherwise, the account's verified email finds the person who has that email, and the account is connected to them, unless they already have an account from that provider. Google's address counts only when Google hosts it: a Gmail address, or a Google Workspace account. 3. Otherwise, hushrun makes a new person with that email. A Google account made with any other address can't join an existing person by its email: the sign-in says an account already has that email. Sign in the way you did before, then connect Google from **Account**. A GitHub account without a verified email, or a Google account whose address Google hasn't verified, can't sign in. **Account** lists your sign-in methods, and disconnects one while another stays. After you disconnect GitHub, invitations to your GitHub login no longer find you. ## Organizations - Your first sign-up makes an organization named after you, with you as its owner, and opens its **Overview**, which shows the command that sets up a repository: `npx hushrun init`. - When an invitation is waiting for you, hushrun makes no organization: you accept the invitation, or create your own. - A sign-in that starts in a terminal, from `hushrun login` or `npx hushrun init`, makes none either. The page that approves the terminal lets you name your organization, accept an invitation, or ask to join the organization the repository records to. - For another organization, open the switcher at the top of the sidebar and choose **Create organization**. It takes a name and a slug for its URLs: 2 to 39 lowercase letters, digits and hyphens, starting with a letter. You're its owner. Each organization has its own members, repositories, machines, agent tokens and plan. A terminal signed in with `hushrun login` acts as you in every organization you belong to. ## Members and roles **Members**, under Organization in the sidebar, lists everyone with their role. | Role | What it may do | |---|---| | Member | See the organization's repositories, checks, history, settings, members and usage. Record results from their own terminals, connect a repository with `npx hushrun init`, and leave | | Admin | All of that, and: invite people and answer requests to join; change roles and capabilities, and remove members, except owners; make and revoke agent tokens; see and revoke every machine; read the audit log; change the organization's and each repository's settings; add repositories to the dashboard; upgrade the plan, set the spend cap and manage billing | | Owner | All of that, and make someone an owner, or change or remove another owner | An organization always keeps an owner: make someone else an owner before the last one leaves or steps down. Owners and admins also get the usage emails described in [Plans and limits](https://hushrun.com/docs/plans.md#at-the-limit). **Approver** is a capability on top of a role, a checkbox on the Members page. It lets a member sign approvals for stages that require one, which admins and owners may do already. Approvals are covered in [Promotion](https://hushrun.com/docs/promotion.md). ## Invite people On **Members**, admins and owners invite by email address or GitHub login, with a role and, for someone who signs approvals, **Approver**. Admins invite admins and members; only owners invite owners. - hushrun sends no email, so tell the person. They see the invitation once they sign in with that email or GitHub account: under **Invitations** in the user menu, which shows a count, and on the page that approves a terminal's sign-in. - An invitation expires after 14 days. **Pending invitations** lists the open ones, and admins revoke them there. - Someone who is already a member, or already invited, can't be invited again. ## Requests to join People can also ask to get in: - When someone who isn't a member runs `npx hushrun init` in a repository that records to your organization, init offers to ask its admins to let them in. `npx hushrun init --yes` asks without the prompt. - The page that approves a terminal's sign-in offers **Request access** to the organization the terminal asked for. Admins and owners find the requests under **Requests to join** on the Members page, and a count beside Members in the sidebar. No email goes out. - **Approve as member** adds the person with the member role. - **Decline** keeps them from asking again for a week. - The person sees the answer under **Invitations**, then runs `npx hushrun init` again. - Someone who is already invited is told to accept the invitation instead. ## Machines Every sign-in with `hushrun login`, including the one `npx hushrun init` starts, registers the machine it runs on, in the organization you approve it for. The machine's key never leaves it, and signs everything it records: hushrun's server records nothing from a person or an agent without it. A browser registers its own key the first time you sign an approval with it in an organization, and an agent token comes with one machine, the key made with it. Machines are per organization: if you work in two, sign in once for each. - **Your machines** are under **Machines** in the user menu, `https://app.hushrun.com/account/machines`, for every organization, revoked ones included, with why each was revoked. Revoking one makes hushrun refuse what it writes from then on, for good: signing in again on that machine is refused, and it signs in again only with a new key. Revoking a terminal's also signs that terminal out: the token it got from `hushrun login` stops working in every organization. - **The organization's machines**, people's and agents', are under **Machines** in the Organization section, for admins and owners. Revoking one makes hushrun refuse what it writes to the organization from then on, for good. Its owner stays signed in, and can sign in on that machine again only with a new key: to keep someone out, remove them. An agent's machine is its token's only one, so the token records nothing more; to stop the agent, revoke the token. - **Unused machines.** A machine of yours that signs no result, event or approval, and isn't signed in again, for 90 days is revoked as unused, and listed that way. `hushrun login` on it brings it back. Agents' machines aren't affected. - **At most 20.** You can have 20 live machines in an organization. Signing in on a 21st is refused, with a link to your machines page: revoke one you no longer use there, then sign in again. - `hushrun logout` revokes the terminal's token and the machine it registered; `hushrun login` on the same machine registers it again. ## Agent tokens **Agents**, in the Organization section, is where admins and owners make tokens for coding agents in sandboxes and for CI outside GitHub Actions. A token records and reads check results as `agent:NAME`, for one repository or the whole organization, up to the number of results a minute set on it, until it expires (after a year at most) or someone revokes it. It does nothing else. - Each token comes with the agent's key, its one machine. The dashboard makes the key in your browser and registers its public half with the token; `hushrun token create` does the same in your terminal. Both show the token and the key once, with the environment variables to set where the agent runs: `HUSHRUN_TOKEN` and `HUSHRUN_MACHINE_KEY`. - Revoking it refuses everything that uses it from then on, and revokes its machine. The results it recorded stay. - `hushrun token create`, `hushrun token list` and `hushrun token revoke` do the same from an admin's terminal. How agents use them: [Agents and sandboxes](https://hushrun.com/docs/agents.md). ## Repositories For a repository on GitHub, `npx hushrun init` connects it to your organization: its GitHub Actions then record and read results with their own ID token, with no secret to copy. CI elsewhere uses an agent token. Both are covered in [In CI](https://hushrun.com/docs/ci.md). - Any member's init connects the repository for its CI. An admin's or owner's init also adds it to the dashboard, with its own page under **Repositories** in the sidebar, and writes its URL on hushrun into `hushrun.yaml`. Until an admin runs init there, its checks show on the organization's Overview, under **Other checks**. - **Add a repository** on the Overview, or the **+** beside Repositories in the sidebar, shows the command, and the repository appears while it runs. - hushrun keeps GitHub's numeric id for each repository, at the latest from the first request its GitHub Actions make. A renamed repository keeps working; one deleted and created again under the same name is refused, with a message that says why. ## A repository's pages Each repository's page has three tabs: - **Overview**: its checks. For each, the newest run, where it ran and who recorded it, and its runs, skips and time saved in the last 30 days. A check that passed and failed on the same code is marked **flaky**. A check opens its history: every run and skip, newest first. - **History**: what hushrun recorded for the repository, newest first: `hushrun run`'s results and the pipeline's events (checks, builds, deploys, approvals). It filters by scope, stage, kind, digest, and whether hushrun accepted the event. An event opens its details, and a digest opens its page: the commits that carried it, each stage's attempts and deploys, and the checks, artifacts and approvals recorded for it. - **Settings**: whose events count, the repository's CI rules, and how CI outside GitHub Actions takes part, with its repository tokens. The organization's **Overview** adds them up: the time `hushrun run`'s skips saved in the last 7 days, a card for each repository, recent activity, flaky checks across the organization, and checks from repositories without a page. ### CI reuses only CI's results A switch under **CI rules** on a repository's Settings, off by default. When it's on, the repository's GitHub Actions skip a check only on passes CI itself recorded. Passes from laptops and agents still let people and agents skip, but never CI. Admins and owners switch it; members see it. ## The organization's settings **Settings**, in the Organization section, lists the stages that take evidence from CI only, in every repository of the organization, such as `production`. Such a stage counts checks, artifacts and deploys only when the repository's own CI signed them; approvals count only from people. - The setting lives on hushrun's server, not in `hushrun.yaml`, so a pull request can't lift it. - It applies to what is recorded while it holds: lifting it later doesn't make that evidence count. - A repository adds stages of its own under **CI rules** on its Settings. - Admins and owners change them; members see them. What a CI-only stage means for promotion: [Promotion](https://hushrun.com/docs/promotion.md). ## Audit log **Audit log**, in the Organization section, is for admins and owners. It lists every admin action in the organization, newest first, with who did it: members, repositories, tokens, machines, approvals and billing. It filters by Members, Repositories, Repository tokens, Agent tokens, Machines, Approvals and Billing. An entry by `hushrun` is the server acting on its own, such as revoking a removed member's machines, or recording a repository's GitHub id. ## Plans and billing **Usage**, in the Organization section, at `https://app.hushrun.com//-/billing`, shows every member the plan and this period's recorded checks. Owners and admins upgrade, set the spend cap and manage billing there. Plans, limits and what counts: [Plans and limits](https://hushrun.com/docs/plans.md). ## Membership is trust No file in your repository lists who may sign. Membership in the organization decides: a teammate's evidence counts from their first sign-in, and nothing they sign after they leave counts, with nothing to merge either way. **Results that let a check skip.** `hushrun run` decides on the newest pass or fail recorded for the same check on the same code ([How skipping works](https://hushrun.com/docs/run.md)) by any of these: a member's terminal, one of the organization's agent tokens, or the GitHub Actions of a repository the organization connected. A teammate's pass lets your CI skip, and CI's lets you skip. Two exceptions: - an agent token for one repository reads only that repository's results; - with [CI reuses only CI's results](#ci-reuses-only-ci) on, the repository's CI skips only on CI's passes. **Evidence that counts for promotion.** An event counts when it is signed by a registered machine of a current member, a machine of one of the organization's agent tokens that covers the repository, a browser key a member registered by signing an approval with it, or the repository's own CI. An approval counts only from people: a member's machine or browser key, never an agent or the CI. At a [CI-only stage](#settings), checks, artifacts and deploys count only from CI. **Removing and revoking** stops what comes next, not what came before: | When | What stops | What stays | |---|---|---| | A member is removed, or leaves | Their access, at once, and their machines in the organization | Their sign-in in their other organizations; the results they recorded | | A machine is revoked | What it writes from then on | What it signed before | | An agent token is revoked | Every request that uses it, and its machine | The results it recorded | | A person's machine goes 90 days unused | What it writes, until its owner signs in on it again | What it signed before | | Someone runs `hushrun logout` | That terminal's token, and its machine | The results it recorded | An event signed before a revocation keeps counting when it carries a trusted timestamp from before it; one without a timestamp stops counting.