NixOS Module Reference
This page is auto-generated from the NixOS module options schema. For a user-friendly guide, see NixOS Module.
services.eka-ci.enable
Whether to enable EkaCI, a Nix-aware Continuous Integration server.
Type: boolean
Default:
false
Example:
true
services.eka-ci.package
The eka-ci package to use.
Type: package
Default:
pkgs.eka-ci
services.eka-ci.credentials
Map of credential name to file path, wired through systemd’s
LoadCredential=. Each entry becomes available inside the unit at
$CREDENTIALS_DIRECTORY/<name> and can be referenced from
ekaci.toml via the systemd-credential credential source, e.g.
services.eka-ci.settings.github_apps = [
{
id = "main";
credentials.systemd-credential.name = "github-app-key";
}
];
Type: attribute set of absolute path
Default:
{ }
Example:
{
github-app-key = "/run/secrets/github-app.json";
s3-creds = "/run/secrets/s3.json";
}
services.eka-ci.dynamicUser
Use systemd’s DynamicUser= to run the service under an ephemeral
user/group. Recommended unless you need a stable UID for filesystem
permissions on shared storage.
Type: boolean
Default:
true
services.eka-ci.environmentFile
Path to a file passed to systemd as EnvironmentFile=. Use this to
provide secrets such as GITHUB_WEBHOOK_SECRET,
GITHUB_OAUTH_CLIENT_SECRET, JWT_SECRET, VAULT_TOKEN, AWS keys,
and any environment variables referenced from
settings.caches.*.credentials.env.vars. The file is read
by systemd at start time and never enters the Nix store.
Type: null or absolute path
Default:
null
Example:
"/run/secrets/eka-ci.env"
services.eka-ci.extraEnvironment
Additional Environment= entries passed to the systemd unit.
Type: attribute set of string
Default:
{ }
Example:
{
RUST_LOG = "eka_ci_server=debug,info";
}
services.eka-ci.group
Group the service runs as when dynamicUser is false.
Ignored when dynamicUser = true.
Type: string
Default:
"eka-ci"
services.eka-ci.openFirewall
Open settings.web.port in the system firewall.
Type: boolean
Default:
false
services.eka-ci.settings
Configuration for EkaCI, serialised verbatim to ekaci.toml. The
submodule is freeform: any key not explicitly modelled here is still
accepted and forwarded as-is to the TOML output.
Type: open submodule of (TOML value)
Default:
{ }
services.eka-ci.settings.build_max_duration_seconds
Hard upper bound, in seconds, on total build wall-clock time.
Type: integer between 60 and 604800 (both inclusive)
Default:
14400
services.eka-ci.settings.build_no_output_timeout_seconds
Number of seconds with no build output after which a build is considered hung.
Type: integer between 30 and 86400 (both inclusive)
Default:
1200
services.eka-ci.settings.caches
List of binary caches the server may push to.
Type: list of (open submodule of (TOML value))
Default:
[ ]
services.eka-ci.settings.caches.*.cache_type
Backend type for this cache.
Type: one of “nix-copy”, “cachix”, “attic”
Example:
"nix-copy"
services.eka-ci.settings.caches.*.credentials
Credential source. One of:
{ env = { vars = [ ... ]; }; }{ file = { path = "/etc/..."; }; }{ aws-profile = { profile = "..."; }; }{ cachix-token = { env_var = "..."; }; }{ vault = { address; secret_path; token_env ? "VAULT_TOKEN"; namespace ? null; }; }{ aws-secrets-manager = { secret_name; region ? null; }; }{ systemd-credential = { name = "..."; }; }"instance-metadata"{ github-app-key-file = { app_id_env; key_file; }; }"none"
Prefer systemd-credential paired with the top-level
services.eka-ci.credentials option to keep secrets out of
the world-readable Nix store.
Type: TOML value
Example:
{
env = {
vars = [
"AWS_ACCESS_KEY_ID"
"AWS_SECRET_ACCESS_KEY"
];
};
}
services.eka-ci.settings.caches.*.destination
Destination URL passed to the chosen backend. Validated for SSRF
unless settings.security.allow_private_cache_hosts is set.
Type: string
Example:
"s3://my-bucket/nix-cache?region=us-east-1"
services.eka-ci.settings.caches.*.id
Cache identifier referenced from .eka-ci/config.json.
Type: string
Example:
"production-s3"
services.eka-ci.settings.caches.*.permissions
Repository/branch access control for this cache.
Type: submodule
Default:
{ }
services.eka-ci.settings.caches.*.permissions.allow_all
When true, ignores allowed_repos and
allowed_branches and grants access to every repository
and branch.
Type: boolean
Default:
true
services.eka-ci.settings.caches.*.permissions.allowed_branches
Glob patterns of branch names permitted to use this entry. Ignored
when allow_all is true.
Type: list of string
Default:
[ ]
Example:
[
"main"
"release/*"
]
services.eka-ci.settings.caches.*.permissions.allowed_repos
Glob patterns of owner/repo strings that are permitted to use this
entry. Ignored when allow_all is true.
Type: list of string
Default:
[ ]
Example:
[
"myorg/*"
]
services.eka-ci.settings.db_path
SQLite database path. When null the server falls back to
$XDG_DATA_HOME/ekaci/sqlite.db which, under this module, resolves
to /var/lib/eka-ci/ekaci/sqlite.db.
Type: null or absolute path
Default:
null
services.eka-ci.settings.default_merge_method
Default merge method used by the @eka-ci merge PR comment command.
Type: one of “merge”, “squash”, “rebase”
Default:
"squash"
services.eka-ci.settings.gitea_instances
List of Gitea instances the server integrates with. Each instance requires a domain and access token. Supports both Gitea.com and self-hosted instances.
Type: list of (open submodule of (TOML value))
Default:
[ ]
services.eka-ci.settings.gitea_instances.*.domain
Gitea instance domain (without protocol).
Type: string
Example:
"gitea.example.com"
services.eka-ci.settings.gitea_instances.*.token
Gitea access token. Avoid setting this in Nix — values
here end up in the world-readable Nix store. Use
services.eka-ci.environmentFile to supply
GITEA_TOKEN instead (for single instance) or configure
tokens via systemd credentials.
Type: null or string
Default:
null
services.eka-ci.settings.github_apps
List of GitHub Apps the server authenticates as.
Type: list of (open submodule of (TOML value))
Default:
[ ]
services.eka-ci.settings.github_apps.*.credentials
Credential source. Same shape as
services.eka-ci.settings.caches.*.credentials.
Type: TOML value
Example:
{
file = {
path = "/etc/eka-ci/github-app.json";
};
}
services.eka-ci.settings.github_apps.*.id
GitHub App identifier referenced from per-app permission lookups.
Type: string
Example:
"main"
services.eka-ci.settings.github_apps.*.permissions
Repository/branch access control for this GitHub App.
Type: submodule
Default:
{ }
services.eka-ci.settings.github_apps.*.permissions.allow_all
When true, ignores allowed_repos and
allowed_branches and grants access to every repository
and branch.
Type: boolean
Default:
true
services.eka-ci.settings.github_apps.*.permissions.allowed_branches
Glob patterns of branch names permitted to use this entry. Ignored
when allow_all is true.
Type: list of string
Default:
[ ]
Example:
[
"main"
"release/*"
]
services.eka-ci.settings.github_apps.*.permissions.allowed_repos
Glob patterns of owner/repo strings that are permitted to use this
entry. Ignored when allow_all is true.
Type: list of string
Default:
[ ]
Example:
[
"myorg/*"
]
services.eka-ci.settings.gitlab_instances
List of GitLab instances the server integrates with. Each instance requires a domain and project access token. Supports both GitLab.com and self-hosted instances.
Type: list of (open submodule of (TOML value))
Default:
[ ]
services.eka-ci.settings.gitlab_instances.*.domain
GitLab instance domain (without protocol).
Type: string
Example:
"gitlab.com"
services.eka-ci.settings.gitlab_instances.*.token
GitLab project access token. Avoid setting this in Nix —
values here end up in the world-readable Nix store. Use
services.eka-ci.environmentFile to supply
GITLAB_TOKEN instead (for single instance) or configure
tokens via systemd credentials.
Type: null or string
Default:
null
services.eka-ci.settings.graph_lru_capacity
Capacity of the in-memory derivation-graph LRU cache, in nodes.
See docs/lru-cache-tuning.md for sizing guidance.
Type: positive integer, meaning >0
Default:
100000
services.eka-ci.settings.logs_dir
Directory where build logs are stored. When null the server
falls back to $XDG_DATA_HOME/ekaci/build-logs.
Type: null or absolute path
Default:
null
services.eka-ci.settings.merge_queue_require_approval
Require approval before building entries pulled from the GitHub merge queue.
Type: boolean
Default:
false
services.eka-ci.settings.oauth
OAuth settings for the (optional) web UI.
Type: open submodule of (TOML value)
Default:
{ }
services.eka-ci.settings.oauth.client_id
GitHub OAuth client ID. May also be supplied via the
GITHUB_OAUTH_CLIENT_ID environment variable (preferred — see
services.eka-ci.environmentFile).
Type: null or string
Default:
null
services.eka-ci.settings.oauth.client_secret
GitHub OAuth client secret. Avoid setting this in Nix — values
here end up in the world-readable Nix store. Use
services.eka-ci.environmentFile to supply
GITHUB_OAUTH_CLIENT_SECRET instead.
Type: null or string
Default:
null
services.eka-ci.settings.oauth.jwt_secret
JWT signing secret. Avoid setting this in Nix. Provide
JWT_SECRET via services.eka-ci.environmentFile. When
omitted entirely, the server generates an ephemeral 256-bit secret
on each start (sessions invalidate across restarts).
Type: null or string
Default:
null
services.eka-ci.settings.oauth.redirect_url
OAuth callback URL. Defaults to
http://{web.address}:{web.port}/github/auth/callback when unset.
Type: null or string
Default:
null
services.eka-ci.settings.require_approval
Require maintainer approval before building PRs from external contributors.
Type: boolean
Default:
false
services.eka-ci.settings.security
Security-related settings.
Type: open submodule of (TOML value)
Default:
{ }
services.eka-ci.settings.security.allow_insecure_webhooks
Allow the server to start without a webhook secret. Intended for local development only; never enable in production.
Type: boolean
Default:
false
services.eka-ci.settings.security.allow_private_cache_hosts
Allow cache destinations whose DNS resolves to private/loopback addresses. Disables built-in SSRF protection; only enable in trusted, isolated networks.
Type: boolean
Default:
false
services.eka-ci.settings.security.audit_hooks
Emit structured audit log records every time a hook runs.
Type: boolean
Default:
true
services.eka-ci.settings.security.max_hook_timeout_seconds
Maximum wall-clock time, in seconds, that any post-build hook is allowed to run.
Type: integer between 1 and 86400 (both inclusive)
Default:
300
services.eka-ci.settings.security.webhook_secret
GitHub webhook HMAC secret. Avoid setting this in Nix. Provide
GITHUB_WEBHOOK_SECRET via
services.eka-ci.environmentFile.
The server refuses to start if no webhook secret is available
unless allow_insecure_webhooks is true.
Type: null or string
Default:
null
services.eka-ci.settings.unix
Unix-domain-socket settings used by the CLI client.
Type: open submodule of (TOML value)
Default:
{ }
services.eka-ci.settings.unix.socket_path
Unix domain socket the CLI client connects to. When null the
server falls back to $XDG_RUNTIME_DIR/ekaci.socket, which under
this module resolves to /run/eka-ci/ekaci.socket.
Type: null or absolute path
Default:
null
services.eka-ci.settings.web
HTTP server settings.
Type: open submodule of (TOML value)
Default:
{ }
services.eka-ci.settings.web.address
IPv4 address the HTTP server binds to.
Type: string
Default:
"127.0.0.1"
services.eka-ci.settings.web.allowed_origins
CORS allow-list. Each entry must be a fully-qualified http:// or
https:// origin with no path, query, fragment, or * wildcard.
An empty list rejects all cross-origin requests.
Type: list of string
Default:
[ ]
Example:
[
"https://app.example.com"
]
services.eka-ci.settings.web.bundle_path
Optional path to a pre-built web UI bundle.
Type: null or absolute path
Default:
null
services.eka-ci.settings.web.port
TCP port the HTTP server binds to.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
3030
services.eka-ci.user
User the service runs as when dynamicUser is false.
Ignored when dynamicUser = true.
Type: string
Default:
"eka-ci"