Configuration

ermite serve reads its settings from the environment.

Required

Variable	Notes
`ERMITE_DATA_DIR`	absolute path of the data root
`ERMITE_PUBLIC_URL`	`http(s)` base URL, no path
`ERMITE_ADMIN_TOKEN`	at least 32 characters; the root credential

export ERMITE_DATA_DIR=/var/lib/ermite
export ERMITE_PUBLIC_URL=https://git.example.com
export ERMITE_ADMIN_TOKEN=$(head -c 32 /dev/urandom | base64)
ermite serve

Server

Variable	Default	Notes
`ERMITE_ADDR`	`:7341`	listen address
`ERMITE_TRUSTED_PROXIES`	empty	comma-separated CIDRs of your TLS proxy, so login rate limits see the real client (`X-Forwarded-For`)
`ERMITE_OWNER`	`owner`	owner login: web header, passkey name, and `<owner>` in CI (`github.repository`). Same rules as repository names
`ERMITE_SOURCE_URL`	`$ERMITE_PUBLIC_URL/ermite`	link to the source (AGPL)
`ERMITE_LOG_LEVEL`	`info`	`trace`, `debug`, `info`, `warn`, `error`
`ERMITE_LOG_FORMAT`	`json`	`json` or `console`

Git

Variable	Default	Notes
`ERMITE_GIT`	`git`	git 2.45 or newer
`ERMITE_GIT_READER`	`ermite-git`	`ermite-git` reads with the ermite-git library where it is faster, and falls back to `git`. `cli` uses `git` for every read: set it and restart if a read looks wrong
`ERMITE_COMMITTER_NAME`	`ermite`	committer of squash and merge commits
`ERMITE_COMMITTER_EMAIL`	`ermite@<public host>`	committer email of squash and merge commits

CI

Variable	Default	Notes
`ERMITE_SECRETS_KEY`	empty	32 random bytes in base64. Encrypts CI secrets and the OIDC key. See below
`ERMITE_CI_LOG_RETENTION`	`90d`	how long runs, jobs, checks and logs are kept. `Nd` or a Go duration (`720h`), at least `1h`
`ERMITE_CI_POLL_TIMEOUT`	`50s`	how long a runner's `FetchJob` call is held when no job is queued, `1s` to `55s`. Keep it below your proxy's response timeout (`25s` behind a proxy that cuts at 30 s)
`ERMITE_CI_ARTIFACTS`	`1`	`0` turns artifacts off
`ERMITE_CI_ARTIFACT_RETENTION`	`90d`	default and maximum `retention-days`, at least one day
`ERMITE_CI_ARTIFACT_QUOTA`	`10GiB`	artifact space per repository, uploads in progress included. Bytes or `KiB`, `MiB`, `GiB`, `TiB`
`ERMITE_CI_ARTIFACT_MAX`	`5GiB`	size of one artifact

`ERMITE_SECRETS_KEY`

head -c 32 /dev/urandom | base64

Store it like the admin token.
Without it, ermite secret set fails, jobs get no secrets and OIDC is off. Variables and environments still work.
The server refuses to start with a different key than the one the secrets were sealed with.
Losing the key loses every secret. A backup without the key reveals none.

Runtime files

The hook socket and scripts git calls on each push live in $ERMITE_DATA_DIR/run/. The socket path must stay under about 100 bytes, so keep ERMITE_DATA_DIR short.

Storage schema

This build uses storage schema 4. Once it has run on your data, an older ermite refuses to start. To downgrade, restore the backup taken before the upgrade.

source

1# Configuration
2
3`ermite serve` reads its settings from the environment.
4
5## Required
6
7| Variable | Notes |
8|---|---|
9| `ERMITE_DATA_DIR` | absolute path of the data root |
10| `ERMITE_PUBLIC_URL` | `http(s)` base URL, no path |
11| `ERMITE_ADMIN_TOKEN` | at least 32 characters; the root credential |
12
13```sh
14export ERMITE_DATA_DIR=/var/lib/ermite
15export ERMITE_PUBLIC_URL=https://git.example.com
16export ERMITE_ADMIN_TOKEN=$(head -c 32 /dev/urandom | base64)
17ermite serve
18```
19
20## Server
21
22| Variable | Default | Notes |
23|---|---|---|
24| `ERMITE_ADDR` | `:7341` | listen address |
25| `ERMITE_TRUSTED_PROXIES` | empty | comma-separated CIDRs of your TLS proxy, so login rate limits see the real client (`X-Forwarded-For`) |
26| `ERMITE_OWNER` | `owner` | owner login: web header, passkey name, and `<owner>` in CI (`github.repository`). Same rules as repository names |
27| `ERMITE_SOURCE_URL` | `$ERMITE_PUBLIC_URL/ermite` | link to the source (AGPL) |
28| `ERMITE_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error` |
29| `ERMITE_LOG_FORMAT` | `json` | `json` or `console` |
30
31## Git
32
33| Variable | Default | Notes |
34|---|---|---|
35| `ERMITE_GIT` | `git` | git 2.45 or newer |
36| `ERMITE_GIT_READER` | `ermite-git` | `ermite-git` reads with the [ermite-git](https://github.com/bnema/ermite-git) library where it is faster, and falls back to `git`. `cli` uses `git` for every read: set it and restart if a read looks wrong |
37| `ERMITE_COMMITTER_NAME` | `ermite` | committer of squash and merge commits |
38| `ERMITE_COMMITTER_EMAIL` | `ermite@<public host>` | committer email of squash and merge commits |
39
40## CI
41
42| Variable | Default | Notes |
43|---|---|---|
44| `ERMITE_SECRETS_KEY` | empty | 32 random bytes in base64. Encrypts CI secrets and the OIDC key. See below |
45| `ERMITE_CI_LOG_RETENTION` | `90d` | how long runs, jobs, checks and logs are kept. `Nd` or a Go duration (`720h`), at least `1h` |
46| `ERMITE_CI_POLL_TIMEOUT` | `50s` | how long a runner's `FetchJob` call is held when no job is queued, `1s` to `55s`. Keep it below your proxy's response timeout (`25s` behind a proxy that cuts at 30 s) |
47| `ERMITE_CI_ARTIFACTS` | `1` | `0` turns artifacts off |
48| `ERMITE_CI_ARTIFACT_RETENTION` | `90d` | default and maximum `retention-days`, at least one day |
49| `ERMITE_CI_ARTIFACT_QUOTA` | `10GiB` | artifact space per repository, uploads in progress included. Bytes or `KiB`, `MiB`, `GiB`, `TiB` |
50| `ERMITE_CI_ARTIFACT_MAX` | `5GiB` | size of one artifact |
51
52### `ERMITE_SECRETS_KEY`
53
54```sh
55head -c 32 /dev/urandom | base64
56```
57
58- Store it like the admin token.
59- Without it, `ermite secret set` fails, jobs get no secrets and OIDC is off. Variables and environments still work.
60- The server refuses to start with a different key than the one the secrets were sealed with.
61- Losing the key loses every secret. A backup without the key reveals none.
62
63## Runtime files
64
65The hook socket and scripts git calls on each push live in `$ERMITE_DATA_DIR/run/`. The socket path must stay under about 100 bytes, so keep `ERMITE_DATA_DIR` short.
66
67## Storage schema
68
69This build uses storage schema 4. Once it has run on your data, an older ermite refuses to start. To downgrade, restore the backup taken before the upgrade.

configuration.md RawHistoryFolder