Tokens
ermite token create <label> [--preset …] [--scope …] [--repo …] [--branch-prefix …] [--expires 30d]
ermite token list
ermite token revoke <id>
The secret is printed once. Presets and --scope add up (issue:write lets a token write issues). The full scope list is in skills/ermite/CLI.md. mr:review lets a token give a merge request verdict (--approve, --request-changes); the cli preset includes it, the agent preset does not. A token created before mr:review existed lacks it: recreate it with --preset cli using the root token or from a signed-in owner web session (an old token lacking mr:review cannot grant it), then replace the stored CLI secret and revoke the old token to keep the owner's rights.
| Preset |
For |
cli |
every scope, the owner's daily use |
agent |
repo:write, mr:write |
ci |
repo:read |
runner |
runner:register: a runner host. It can read the code and secrets of every repository, so give it only to runners you operate |
Release publishing
release:write permits creating, editing and deleting releases and their assets;
it is included in the cli preset, not agent or ci. Private repository reads
also need repo:read. Branch-limited tokens cannot write releases, even with
that scope. CI jobs publish using their job token with contents: write under
permissions, not a stored-token scope. See releases.
Branch-limited tokens
For an AI agent that should propose changes, not publish them:
ermite token create claude --preset agent --scope repo:read --repo myrepo --branch-prefix agent/claude/
--branch-prefix is repeatable (up to 8), each ending with /.
The token can:
- push, force-push and delete branches under its prefixes;
- open, comment on and close merge requests; with
mr:review, give verdicts;
- with
issue:write, open, comment on, close and reopen issues of the repositories where they are enabled;
- with
mr:merge, merge into a branch under its prefixes;
- read CI runs, logs and checks; with
ci:write, cancel and re-run runs of its own branches;
- create tokens whose prefixes lie within its own.
The token cannot:
- push any other ref (
main, other branches, tags, notes). The whole push is refused and the message names the ref;
- create, delete or configure a repository;
- create, edit or delete releases or upload assets;
- open web sessions or get owner rights, even with every scope;
- manage runners, even with
runner:register;
- get trusted CI runs (no secrets). See CI trust.
ermite token list shows a branches column (all when unlimited); --json has branch_prefixes.
source
1# Tokens
2
3```sh
4ermite token create <label> [--preset …] [--scope …] [--repo …] [--branch-prefix …] [--expires 30d]
5ermite token list
6ermite token revoke <id>
7```
8
9The secret is printed once. Presets and `--scope` add up (`issue:write` lets a token write issues). The full scope list is in [`skills/ermite/CLI.md`](../skills/ermite/CLI.md). `mr:review` lets a token give a merge request verdict (`--approve`, `--request-changes`); the `cli` preset includes it, the `agent` preset does not. A token created before `mr:review` existed lacks it: recreate it with `--preset cli` using the root token or from a signed-in owner web session (an old token lacking `mr:review` cannot grant it), then replace the stored CLI secret and revoke the old token to keep the owner's rights.
10
11| Preset | For |
12|---|---|
13| `cli` | every scope, the owner's daily use |
14| `agent` | `repo:write`, `mr:write` |
15| `ci` | `repo:read` |
16| `runner` | `runner:register`: a runner host. It can read the code and secrets of every repository, so give it only to runners you operate |
17
18## Release publishing
19
20`release:write` permits creating, editing and deleting releases and their assets;
21it is included in the `cli` preset, not `agent` or `ci`. Private repository reads
22also need `repo:read`. Branch-limited tokens cannot write releases, even with
23that scope. CI jobs publish using their job token with `contents: write` under
24`permissions`, not a stored-token scope. See [releases](releases.md).
25
26## Branch-limited tokens
27
28For an AI agent that should propose changes, not publish them:
29
30```sh
31ermite token create claude --preset agent --scope repo:read --repo myrepo --branch-prefix agent/claude/
32```
33
34`--branch-prefix` is repeatable (up to 8), each ending with `/`.
35
36The token **can**:
37
38- push, force-push and delete branches under its prefixes;
39- open, comment on and close merge requests; with `mr:review`, give verdicts;
40- with `issue:write`, open, comment on, close and reopen issues of the repositories where they are enabled;
41- with `mr:merge`, merge into a branch under its prefixes;
42- read CI runs, logs and checks; with `ci:write`, cancel and re-run runs of its own branches;
43- create tokens whose prefixes lie within its own.
44
45The token **cannot**:
46
47- push any other ref (`main`, other branches, tags, notes). The whole push is refused and the message names the ref;
48- create, delete or configure a repository;
49- create, edit or delete releases or upload assets;
50- open web sessions or get owner rights, even with every scope;
51- manage runners, even with `runner:register`;
52- get trusted CI runs (no secrets). See [CI trust](ci.md#trust).
53
54`ermite token list` shows a `branches` column (`all` when unlimited); `--json` has `branch_prefixes`.