detached 3483340

README.md RawHistoryFolder

Read-only mirror. Development happens at git.bnema.dev; issues and pull requests are closed here.

Features

  • GitHub Actions, as is: your .github/workflows run unchanged, marketplace actions included
  • Isolated runner: ermite-runner runs each job in a Firecracker microVM when KVM is available, else in a container
  • CLI-first: repositories, merge requests, reviews and CI all work from the ermite CLI, for you and for AI agents
  • Safe for agents: an agent token can only push its own branches; you review and merge
  • Git over HTTPS, web interface with live updates

Status: early development.

GitHub Actions

Push a repository with a .github/workflows folder and its workflows run, the same YAML you use on GitHub:

  • Events: push, pull_request, pull_request_target, workflow_dispatch, schedule, workflow_run, create, delete
  • Matrix, needs, concurrency, reusable workflows, job outputs and summaries
  • Secrets, variables, environments and OIDC (id-token: write)
  • actions/checkout, actions/cache, setup-*, upload-artifact / download-artifact v4
  • Actions from github.com or from your own ermite repositories
  • Each job is a check on the commit and the merge request; failing checks block the merge

A feature ermite does not support fails with not supported yet: <feature>, never silently.

Runner

Jobs run on ermite-runner hosts, one fresh sandbox per job:

  • microVM (Firecracker) when /dev/kvm is available: each job gets its own kernel, destroyed at the end
  • container with its own Docker daemon otherwise
ermite token create runner-1 --preset runner   # then register the runner with this token
ermite runner list

CI turns on as soon as a runner is registered. Details: docs/ci.md.

Run

docker build -t ermite .
token=$(head -c 32 /dev/urandom | base64)   # keep it: it is the root credential
docker run -d -p 127.0.0.1:7341:7341 -v ermite-data:/data \
  -e ERMITE_PUBLIC_URL=http://localhost:7341 -e ERMITE_ADMIN_TOKEN="$token" ermite

Without Docker, set ERMITE_DATA_DIR, ERMITE_PUBLIC_URL and ERMITE_ADMIN_TOKEN, then run ermite serve. Requires git 2.45 or newer. Put a TLS proxy in front of it.

All settings: docs/configuration.md.

Use

Point the CLI at the server:

ermite config set url https://git.example.com
ermite config set token.cmd 'pass show ermite/token'   # any command that prints the token

Then:

ermite repo create myrepo
git push https://x:<token>@git.example.com/myrepo.git main   # prefer a credential helper
ermite mr create myrepo --source feature --title "Add feature"
ermite web login   # one-time link to sign in to the web interface

Pushing to a new name also creates a private repository.

ermite mr create and ermite mr close print a confirmation followed by the full merge request web URL on its own line. With --json, merge request objects (create, show, list, close and merge) include url alongside the other fields.

Agent workflow

You and the agent use the same CLI. The difference is the token: the agent's is limited to its own branches. It can never push main, tags or settings, and its CI runs get no secrets.

1. You give the agent a token limited to agent/claude/*:

ermite token create claude --preset agent --scope repo:read --repo myrepo --branch-prefix agent/claude/ --expires 30d

2. The agent pushes and opens a merge request:

export ERMITE_URL=https://git.example.com ERMITE_TOKEN=<agent token>
git push origin agent/claude/fix-login
ermite mr create myrepo --source agent/claude/fix-login --title "Fix login redirect"
ermite run watch myrepo <run id>         # follow its CI

3. You review:

ermite mr show myrepo 1 --diff
ermite mr comment myrepo 1 -m "Handle the empty case" --path auth.go --line 42 --side new

4. The agent reads your comments and pushes again:

ermite watch myrepo --json               # live events: pushes, merge requests, comments
ermite mr show myrepo 1 --since-last-read --mark-read

5. You merge (or click Merge in the web interface):

ermite mr merge myrepo 1 --head <head id> --mode squash --delete-branch

Give the agent the skills/ermite skill so it knows the CLI. Rules of agent tokens: docs/tokens.md.

Documentation

License

AGPL-3.0-or-later. See LICENSE.

source
1<h1 align="center">ermite</h1>
2
3<p align="center">
4  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square" alt="License: AGPL-3.0"></a>
5  <a href="https://github.com/bnema/ermite/commits/main"><img src="https://badgen.net/github/last-commit/bnema/ermite/main?icon=github" alt="Last commit"></a>
6  <a href="https://github.com/bnema/ermite/stargazers"><img src="https://badgen.net/github/stars/bnema/ermite?icon=github" alt="GitHub stars"></a>
7</p>
8
9<p align="center">A single-user Git forge in one Go binary.</p>
10
11> Read-only mirror. Development happens at git.bnema.dev; issues and pull requests are closed here.
12
13---
14
15## Features
16
17- **GitHub Actions, as is**: your `.github/workflows` run unchanged, marketplace actions included
18- **Isolated runner**: [ermite-runner](https://github.com/bnema/ermite-runner) runs each job in a Firecracker microVM when KVM is available, else in a container
19- **CLI-first**: repositories, merge requests, reviews and CI all work from the `ermite` CLI, for you and for AI agents
20- **Safe for agents**: an agent token can only push its own branches; you review and merge
21- Git over HTTPS, web interface with live updates
22
23Status: early development.
24
25## GitHub Actions
26
27Push a repository with a `.github/workflows` folder and its workflows run, the same YAML you use on GitHub:
28
29- Events: `push`, `pull_request`, `pull_request_target`, `workflow_dispatch`, `schedule`, `workflow_run`, `create`, `delete`
30- Matrix, `needs`, `concurrency`, reusable workflows, job outputs and summaries
31- Secrets, variables, environments and OIDC (`id-token: write`)
32- `actions/checkout`, `actions/cache`, `setup-*`, `upload-artifact` / `download-artifact` v4
33- Actions from github.com or from your own ermite repositories
34- Each job is a check on the commit and the merge request; failing checks block the merge
35
36A feature ermite does not support fails with `not supported yet: <feature>`, never silently.
37
38### Runner
39
40Jobs run on [ermite-runner](https://github.com/bnema/ermite-runner) hosts, one fresh sandbox per job:
41
42- **microVM** (Firecracker) when `/dev/kvm` is available: each job gets its own kernel, destroyed at the end
43- **container** with its own Docker daemon otherwise
44
45```sh
46ermite token create runner-1 --preset runner   # then register the runner with this token
47ermite runner list
48```
49
50CI turns on as soon as a runner is registered. Details: [docs/ci.md](docs/ci.md).
51
52## Run
53
54```sh
55docker build -t ermite .
56token=$(head -c 32 /dev/urandom | base64)   # keep it: it is the root credential
57docker run -d -p 127.0.0.1:7341:7341 -v ermite-data:/data \
58  -e ERMITE_PUBLIC_URL=http://localhost:7341 -e ERMITE_ADMIN_TOKEN="$token" ermite
59```
60
61Without Docker, set `ERMITE_DATA_DIR`, `ERMITE_PUBLIC_URL` and `ERMITE_ADMIN_TOKEN`, then run `ermite serve`. Requires git 2.45 or newer. Put a TLS proxy in front of it.
62
63All settings: [docs/configuration.md](docs/configuration.md).
64
65## Use
66
67Point the CLI at the server:
68
69```sh
70ermite config set url https://git.example.com
71ermite config set token.cmd 'pass show ermite/token'   # any command that prints the token
72```
73
74Then:
75
76```sh
77ermite repo create myrepo
78git push https://x:<token>@git.example.com/myrepo.git main   # prefer a credential helper
79ermite mr create myrepo --source feature --title "Add feature"
80ermite web login   # one-time link to sign in to the web interface
81```
82
83Pushing to a new name also creates a private repository.
84
85`ermite mr create` and `ermite mr close` print a confirmation followed by the full
86merge request web URL on its own line. With `--json`, merge request objects
87(create, show, list, close and merge) include `url` alongside the other fields.
88
89## Agent workflow
90
91You and the agent use the same CLI. The difference is the token: the agent's is limited to its own branches. It can never push `main`, tags or settings, and its CI runs get no secrets.
92
93**1. You give the agent a token** limited to `agent/claude/*`:
94
95```sh
96ermite token create claude --preset agent --scope repo:read --repo myrepo --branch-prefix agent/claude/ --expires 30d
97```
98
99**2. The agent pushes and opens a merge request:**
100
101```sh
102export ERMITE_URL=https://git.example.com ERMITE_TOKEN=<agent token>
103git push origin agent/claude/fix-login
104ermite mr create myrepo --source agent/claude/fix-login --title "Fix login redirect"
105ermite run watch myrepo <run id>         # follow its CI
106```
107
108**3. You review:**
109
110```sh
111ermite mr show myrepo 1 --diff
112ermite mr comment myrepo 1 -m "Handle the empty case" --path auth.go --line 42 --side new
113```
114
115**4. The agent reads your comments and pushes again:**
116
117```sh
118ermite watch myrepo --json               # live events: pushes, merge requests, comments
119ermite mr show myrepo 1 --since-last-read --mark-read
120```
121
122**5. You merge** (or click Merge in the web interface):
123
124```sh
125ermite mr merge myrepo 1 --head <head id> --mode squash --delete-branch
126```
127
128Give the agent the [`skills/ermite`](skills/ermite/SKILL.md) skill so it knows the CLI. Rules of agent tokens: [docs/tokens.md](docs/tokens.md).
129
130## Documentation
131
132- [Configuration](docs/configuration.md): environment variables
133- [CLI](docs/cli.md): config file, commands, JSON output
134- [Git over HTTP](docs/git-http.md): URLs and authentication
135- [Tokens](docs/tokens.md): scopes, presets, branch-limited tokens
136- [Merge requests](docs/merge-requests.md)
137- [Issues](docs/issues.md)
138- [Commit signatures](docs/commit-signatures.md): SSH and OpenPGP badges, trusted keys
139- [Web sign-in](docs/web-sign-in.md): passkeys and one-time links
140- [CI](docs/ci.md): runners, trust, concurrency, reusable workflows
141  - [CI events](docs/ci-events.md)
142  - [OIDC](docs/ci-oidc.md)
143  - [Artifacts](docs/ci-artifacts.md)
144- [Development](docs/development.md): build, tests, architecture
145
146## License
147
148AGPL-3.0-or-later. See [LICENSE](LICENSE).

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 4

Tags 45

↑↓ moveenter openesc close