The Mandate is where you say what CoRoid may do without asking a person. It has its own place in the navigation, next to Quality Control, and two parts: Overview tells you what is set, and Settings is where you change it.
What the Overview tells you
The Overview answers one question: what does CoRoid do without asking you?
It starts with one sentence, for example "CoRoid starts security fixes by itself and is learning to merge in shadow. Every other step waits for you." If CoRoid also fixes or blocks pull requests by itself, a second line says so. Under it are the four steps the Mandate decides, in the order work goes through them:
| Step | What it means |
|---|---|
| Start work | CoRoid starts a piece of work nobody asked for, under one of your objectives |
| Merge | CoRoid merges a pull request |
| Deploy | CoRoid deploys to an environment |
| Roll back | CoRoid undoes a failed deployment |
Each step says one of these:
- Asks you. No grant covers it, so a person does it.
- Learning in shadow. A grant covers it, but only records what it would have done. The step says since when, and what it would have done so far.
- Does it itself. An active grant covers it, and the step says for which work and how it tells you.
- Stopped by CoRoid. CoRoid stopped the step's grant itself. Open it to see why.
- Security fixes only (Start work). CoRoid starts security fixes under Security's own settings, and a person starts everything else.
A step opens its grant in Settings, or a new grant for that step.
Below the steps:
- Always a person's call: the protected paths and the most pull requests CoRoid keeps open in a project. A change to a protected path is never merged or deployed by CoRoid, whatever a grant says.
- Objectives: what CoRoid works toward and what it may spend, and what happens to that work.
- Projects: a project that is paused, or that narrows a grant, has a row. The rest follow the organization.
Owners and admins can pause autonomy from the top of the Overview.
Set it up
- Open Mandate → Settings and choose Start from a preset, or New grant for one step.
- The grant starts in shadow. Let it run for a while on your real work.
- Open the grant and read what it would have done. When the record convinces you, choose Make active.
- If you want to hear about it in Slack or Telegram, add a route for What CoRoid does under Settings → Connections → Notification routes.
You can return a grant to shadow, or pause autonomy, at any time.
Settings
Settings has the organization first and then each project. Each row says what is set; selecting it opens its editor in a side panel. Nothing is edited in the page itself.
| Group | Rows |
|---|---|
| Autonomy | Pause, with any holds and suspensions; the Recovery reserve |
| Grants | One row per grant, with Start from a preset and New grant |
| Objectives | One row per objective, with New objective |
| Limits | Protected paths, Delivery actions, Open pull requests, Agents |
| History | Every change to the Mandate and every decision made under it |
A project's page has its own pause, what it has of each grant, and its history. Objectives and limits are the organization's.
Grants
A grant is one thing CoRoid may do without a person. Its row names it, for example "Merge work a person asked for", and says how far it goes:
Graded Low, in every project. At most 5 a day. It tells you first, and waits 10 minutes for a Stop.
In its panel you edit it part by part: the step, whose work it applies to, how risky a change it covers, which projects, the limits, the paths it leaves alone, and how it tells you.
A grant that deploys can also limit the changes in one deployment: how many merged pull requests a release may carry for CoRoid to deploy it. A bigger release is left for a person to deploy, so a batch that only fails together never reaches production without one.
A grant covers one of the four steps, or one of two things CoRoid does on pull requests:
- Fix pull requests. When the checks fail on a pull request of CoRoid's own work, CoRoid starts a round that fixes them. Without a grant for that work it leaves the failure to the person reviewing. When you choose "Fix failing checks" yourself, no grant is needed.
- Block pull requests. When CoRoid Review finds a problem that must be fixed, it requests changes, so the pull request waits for a person. Without a grant for the project, the review is a comment and its check does not fail. A block grant covers every pull request in its projects, whoever opened it and however risky it is, except where it touches a path the grant leaves alone.
Both were things CoRoid already did before they were grants. Each organization has them as active grants, so nothing changed when they became decisions: narrow one to some projects, or revoke it, and CoRoid stops. A pause stops them too.
A grant's panel offers only what its step asks. Starting work, fixing and rolling back are decided before there is a change to grade, so they have no risk level or paths to leave alone. A block grant has no "whose work": it covers every pull request.
CoRoid no longer asks about implementing work: starting work is the decision at that moment. A grant for implementing says so, and can be revoked.
A grant starts in shadow
A new grant allows nothing. In shadow CoRoid records what the grant would have allowed, so you can read that before you rely on it. Make active puts it in force.
An edit that lets a grant do more sends an active grant back to shadow. An edit that only narrows it does not.
What it would have done
Open a grant to see:
- how often CoRoid asked it, and what it would have allowed in shadow;
- for a grant that merges, the last 30 days: how many pull requests of that kind of work merged, how many the grant would have merged, why not the rest, and each one it would have merged that was later reverted, fixed or followed up;
- what the grant needs before it can become active.
A grant for changes graded Low needs nothing more: rules give that grade. A grant for changes graded Medium depends on a model, so it becomes active only on a record: at least 30 judged pull requests of its class with no false approval, and at least 10 seeded bad changes, every one blocked. Until then the grant says what is still missing.
Start from a preset
Start from a preset fills the Mandate with a set of grants, all in shadow:
| Preset | What it adds |
|---|---|
| Repair | Start work under your objectives |
| Merge | Repair, and merge that work when it is graded Low |
| Ship | Merge, and deploy to one environment you name |
| Closed loop | Ship, and roll that environment back when a deployment fails |
| Keep dependencies current | Merge dependency updates graded Low |
A preset never makes a grant active, and it adds nothing you already have.
A project can narrow a grant
The organization's grants are the default for every project. On a project's page, select a grant to turn it off for that project, lower its level, shorten its limits or add paths to leave alone. A project cannot give itself more than the organization gives.
When CoRoid stops a grant itself
- Held. CoRoid's reviewer or its risk grader changed, and the grant has not been measured on the new version yet. It becomes active again by itself when it has.
- Suspended by its breaker. The merges the grant let through were later reverted, fixed or followed up more often than the merges people made in the same projects. One failure never does this. The grant shows both counts. A person lifts the suspension and says why.
What a grant can merge
A grant that merges says whose work it covers. It still covers only changes graded at its level or lower.
| Work | What it covers |
|---|---|
| Work people asked for | A pull request CoRoid opened for a task a person asked for |
| Work under an objective | A pull request CoRoid opened for work it started under one of your objectives |
| Dependency updates | A pull request by Dependabot or Renovate (on GitLab, a merge request that a project's or group's access token bot opened from a renovate/ branch) that updates npm packages, each to a patch or minor version on the same version line, published at least 7 days ago, with no new install script, a lockfile that matches package.json, and no open security advisory. Such an update is graded Low once its 7 days have passed |
| Trusted people | A pull request by a member the grant names, when every commit since its base was authored and committed by that member's linked GitHub account and GitHub verified its signature. On GitLab, a merge request the member's linked GitLab account opened, when GitLab verified every commit's signature and each commit's author and committer email is one the member confirmed on GitLab. A commit made in the web editor, or pushed by somebody else, leaves it for a person |
How a grant merges
The merge plan in the Factory puts a pull request a grant covers under CoRoid can merge now, and the merge train merges it. At the moment it merges, CoRoid asks the Mandate again, so a pause, a hold, a spent limit or a new commit since the plan was made stops it.
The merge commit names the grant and its version. The merge counts as the grant's, for the person the grant names as accountable, in the History and in the grant's limits.
In shadow, the merge plan says the grant would merge the pull request, and a person decides.
Announce, and Stop
A grant says how it tells you about a merge:
- First, and waits for a Stop. When the merge train takes the pull request, the grant's accountable person and the person who asked for the work get a notification. CoRoid merges it when the window ends, for example after 10 minutes, unless somebody presses Stop on the notification or in the merge plan, or, with a linked account, on its post in Slack or Telegram. A stopped pull request waits for a person.
- After each. You are told when it has merged.
Linking your accounts
A grant for trusted people, and CoRoid Approvals, need to know which GitHub or GitLab account is yours. Stop in Slack or Telegram needs to know which Slack or Telegram account is yours. In Profile → Linked accounts, link each one; the platform confirms it. CoRoid keeps the account's id and name, never a token. For GitLab it also keeps a digest of each email you confirmed there (not the emails), which is how it knows a commit is yours; link again after you add an email. Unlink removes it all. Where your organization connects a self-managed GitLab, that GitLab has a row of its own once an owner or admin has set it up (Linking people's accounts on your GitLab).
Objectives
An objective says what CoRoid works toward on its own, in which projects, and how much it may spend. Earlier versions called objectives mandates; Objectives describes them in full.
An objective gives CoRoid a goal and a budget. Requests from your systems that an objective takes on start as described in When the work starts. Work CoRoid files by itself under an objective, such as a follow-up when a change did not achieve its outcome, needs an active grant for Start work; until then it waits for a person to start it. Security's fixes are the exception: they start under Security's own settings.
Limits
What CoRoid may never do by itself, whatever a grant says:
- Protected paths. A person decides every change to these. CoRoid protects sign-in and access, billing and payments, secrets and credentials, cryptography, database migrations, lockfiles, CI pipelines, and containers and infrastructure, and you can add paths of your own. Only an owner can remove one of CoRoid's, with a reason that is recorded.
- Delivery actions. The most any grant may do here: merge, deploy and roll back, each allowed, asked or denied.
- Open pull requests. How many of its own pull requests CoRoid keeps open in a project. At the limit, work it starts by itself waits; a person's request always starts.
- Agents. How deep an agent may go, and whether automations and schedules may create tasks. Whether CoRoid Review may block a pull request is a grant.
History
Every change to the Mandate and every decision made under it, newest first: who published or changed a grant, what CoRoid was allowed or not allowed to do and why, and what people answered when CoRoid asked.
When CoRoid asks you
Some actions need a person's answer first. Each is a row under Needs you in the Factory: what CoRoid asks to do, where, and why. Approve once lets it take that action one time. Decline keeps it from taking it. See The Factory.
Who can change it
Owners and admins change the Mandate. Members can read all of it. CoRoid's own agents and service accounts cannot change it at all.
Every decision made under a grant is also written to your organization's audit stream, as CoRoid's, with the grant and its version.