ermite

A single-user Git forge in one Go binary.

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
• Releases with a GitHub-compatible API, CLI and web downloads; assets and CI artifacts on disk or S3-compatible storage
• 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, download a Linux binary (amd64 or arm64) from the releases, 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

• Configuration: environment variables
• CLI: config file, commands, JSON output
• Git over HTTP: URLs and authentication
• Push mirror: push repositories to a remote over SSH
• Bernard: daily dependency updates in the Inbox
• Tokens: scopes, presets, branch-limited tokens
• Merge requests
• Issues
• Commit signatures: SSH and OpenPGP badges, trusted keys
• Web sign-in: passkeys and one-time links
• Keyboard shortcuts: web section navigation and page actions
• CI: runners, trust, concurrency, reusable workflows
  • CI events
  • OIDC
  • Artifacts
• Development: build, tests, architecture

License

AGPL-3.0-or-later. See LICENSE.

Issue and merge request creation accept body/description text only from files: issue create <repo> --title T [--body-file PATH|-] and mr create <repo> --source B --title T [--description-file PATH|-]. Both file flags are optional; omitting them creates empty text. - reads stdin, with a 1 MiB limit shared with edit commands. Inline --body and --description are not accepted for these commands. Repository descriptions remain inline.