v0.28.0 fca9155

tokens.md RawHistoryFolder

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

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;
  • 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## Branch-limited tokens
19
20For an AI agent that should propose changes, not publish them:
21
22```sh
23ermite token create claude --preset agent --scope repo:read --repo myrepo --branch-prefix agent/claude/
24```
25
26`--branch-prefix` is repeatable (up to 8), each ending with `/`.
27
28The token **can**:
29
30- push, force-push and delete branches under its prefixes;
31- open, comment on and close merge requests; with `mr:review`, give verdicts;
32- with `issue:write`, open, comment on, close and reopen issues of the repositories where they are enabled;
33- with `mr:merge`, merge into a branch under its prefixes;
34- read CI runs, logs and checks; with `ci:write`, cancel and re-run runs of its own branches;
35- create tokens whose prefixes lie within its own.
36
37The token **cannot**:
38
39- push any other ref (`main`, other branches, tags, notes). The whole push is refused and the message names the ref;
40- create, delete or configure a repository;
41- open web sessions or get owner rights, even with every scope;
42- manage runners, even with `runner:register`;
43- get trusted CI runs (no secrets). See [CI trust](ci.md#trust).
44
45`ermite token list` shows a `branches` column (`all` when unlimited); `--json` has `branch_prefixes`.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 42

↑↓ moveenter openesc close