Coordinator command and configuration

Runtime configuration owned by the ngit-ci coordinator.

Owned by ngit-ciVerified 0.1.0-rc.2 @ 68b12d3236b6upcoming generated reference

Upcoming CI surface

These pages are generated from an unreleased ngit-ci commit. The interface may change before the next release.

Command syntax

Usage: ngit-ci [OPTIONS] --repos <REPOS>

Self-hosted CI coordinator for Nostr Git repositories

Loading behaviour

ngit-ci automatically reads a .env file from its working directory. Variables already present in the process environment take precedence over .env values. The complete precedence order is cli → process_environment → dotenv → defaults.

Options

This surface exports 36 public configuration entries. Pattern entries describe a family of names, not one concrete environment variable.

• NGIT_CI_INDEX_RELAYS — Comma-separated list of index relay URLs. These relays index NIP-34 repository announcements (kind 30617) network-wide. They are used solely for discovery: the coordinator learns which repos exist matching the whitelist, and which relays host each repo. Live 30618 / 1618 / 1619 subscriptions are then opened directly against those repo-announced relays. Defaults to a single entry: wss://index.ngit.dev.
  • CLI: --index-relays <INDEX_RELAYS>
  • Value: type relay_url; cardinality 1+; default wss://index.ngit.dev; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: index-relays-non-empty, index-relay-url-format
• NGIT_CI_NOSTR_SECRET_RELAYS — Coordinator inbox relays for encrypted Repository Secret Updates. Empty disables Nostr secret intake. When configured, the same recipient and every normalized relay URL are advertised to all maintainers of repositories admitted by --repos.
  • CLI: --nostr-secret-relays <NOSTR_SECRET_RELAYS>
  • Value: type relay_url; cardinality 0+; default —; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: nostr-secret-relay-url-format
• NGIT_CI_REPOS — Comma-separated list of repositories to watch. Each entry is one of: - npub1... → all repos from this author - npub1.../identifier → a specific repo Hex pubkeys are also accepted in place of npubs. Bare identifiers (no pubkey) are not supported and will be skipped.
  • CLI: --repos <REPOS>
  • Value: type repository_selector; cardinality 1+; default —; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: watched-repositories-valid-non-empty, repository-secret-aliases-unique
• NGIT_CI_EXECUTION_POLICY — When admitted repositories may execute ordinary CI triggers: request-required (default) or automatic. Admission remains controlled by --repos. Under request-required, a valid kind-9843 Service Request must be observed before push and pull request workflows run. A kind-9840 Manual Trigger remains a one-shot explicit request and does not need a standing Service Request.
  • CLI: --execution-policy <EXECUTION_POLICY>
  • Value: type enum; cardinality 1; default request-required; values request-required, automatic
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_ADDITIONAL_REQUESTERS — Comma-separated npubs or hex pubkeys whose Service Requests may enable work for an admitted repository even when they are not maintainers. This is a local acceptance policy and does not grant repository authority.
  • CLI: --additional-requesters <ADDITIONAL_REQUESTERS>
  • Value: type nostr_public_key; cardinality 0+; default empty string; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: additional-requester-format
• NGIT_CI_LOG_LEVEL — Log level (e.g. info, debug, ngit_ci=debug,nostr=info)
  • CLI: --log-level <LOG_LEVEL>
  • Value: type tracing_filter; cardinality 1; default info; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_WORK_DIR — Local working directory for embedded runner clones and job state
  • CLI: --work-dir <WORK_DIR>
  • Value: type path; cardinality 1; default .ngit-ci-work; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_RUNNER — Runner backend to use for watched repositories. - embedded-act (default): execute jobs locally with act against the host's Docker-compatible daemon. - socket-adapter: render each job into a self-contained script and submit it to the sandbox adapter listening on --adapter-socket (Loom execution-adapter contract; see docs/execution-adapter-protocol.md).
  • CLI: --runner <RUNNER>
  • Value: type enum; cardinality 1; default embedded-act; values embedded-act, socket-adapter
  • Runtime: scope coordinator; reload restart required
  • Rules: socket-adapter-requires-socket
• NGIT_CI_ADAPTER_SOCKET — Path of the sandbox adapter's Unix domain socket. Required when --runner socket-adapter is selected. The adapter is a dumb daemon following the Loom execution-adapter contract: one job per connection, streamed output, immediate rejection when its capacity is exhausted (surfaced as a failed, retryable kind-9842 result). Compatible adapters include the first-party ngit-ci-adapter-microvm and the Loom shell/multipass/lima adapters.
  • CLI: --adapter-socket <ADAPTER_SOCKET>
  • Value: type path; cardinality 0–1; default —; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: socket-adapter-requires-socket
• NGIT_CI_ACT_PATH — Path/name of the act executable used by the embedded runner
  • CLI: --act-path <ACT_PATH>
  • Value: type executable; cardinality 1; default act; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: act-path-non-empty
• NGIT_CI_ACT_PLATFORMS — Comma-separated runs-on platform → container image mappings passed to act as -P flags (e.g. ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest). Explicit mappings keep the embedded runner deterministic and non-interactive: without them, act prompts for a default image on first run and would block a headless service.
  • CLI: --act-platforms <ACT_PLATFORMS>
  • Value: type platform_mapping; cardinality 0+; default ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest, ubuntu-24.04=ghcr.io/catthehacker/ubuntu:act-24.04, ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: act-platform-mapping-format
• NGIT_CI_ACT_CACHE_ENABLED — Enable act's local actions/cache-compatible server. Storage is partitioned by repository perspective and trigger-author trust so third-party PRs cannot write into maintainer caches. The first-party microVM adapter persists the selected partition outside each disposable guest
  • CLI: --act-cache-enabled <ACT_CACHE_ENABLED>
  • Value: type boolean; cardinality 1; default true; values true, false
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_ACT_CACHE_MAX_BYTES — Maximum actions/cache server bytes retained for each repository perspective. Least-recently-used trust scopes are evicted after runs
  • CLI: --act-cache-max-bytes <ACT_CACHE_MAX_BYTES>
  • Value: type byte_count; cardinality 1; default 10737418240; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: act-cache-max-bytes-positive
• NGIT_CI_DOCKER_HOST — Docker-compatible daemon socket handed to act as DOCKER_HOST (e.g. unix:///run/user/1000/podman/podman.sock for rootless Podman). Leave unset to use the environment / default Docker socket.
  • CLI: --docker-host <DOCKER_HOST>
  • Value: type socket_url; cardinality 0–1; default —; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_ACT_CONTAINER_DAEMON_SOCKET — Value for act's --container-daemon-socket flag: the daemon socket bind-mounted into job containers so workflow steps can talk to the container daemon (docker-in-docker style). Defaults to -, which disables the mount. Set an explicit socket URI (e.g. unix:///var/run/docker.sock) only if jobs genuinely need daemon access: the mount hands untrusted workflow code control of the container daemon and lets it spawn sibling containers outside any job resource limits.
  • CLI: --act-container-daemon-socket <ACT_CONTAINER_DAEMON_SOCKET>
  • Value: type socket_url_or_disabled; cardinality 1; default -; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: act-container-daemon-socket-non-empty
• NGIT_CI_ACT_CONTAINER_OPTIONS — Docker-run-style options applied to every act job container, passed to act as --container-options (e.g. --memory=4g --memory-swap=4g --cpus=2 --pids-limit=2048). This is the primary mechanism for capping the CPU / RAM a CI job can take from the host: job containers are created by the container daemon, outside the coordinator's own cgroup, so service-level limits do not reach them. The effective host ceiling is --max-concurrent-jobs × these per-container limits. Caveat: act only applies these options to job containers derived from runs-on platform images. Jobs that declare their own container: (and all services:) use the workflow-supplied options instead.
  • CLI: --act-container-options <ACT_CONTAINER_OPTIONS>
  • Value: type shell_words; cardinality 0–1; default empty string; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: act-container-options-balanced-quotes
• NGIT_CI_ACT_BIND_WORKSPACE — Bind-mount the workspace into job containers (true) or let act copy the checkout into a Docker volume when actions/checkout runs (false). Bind-mounting is faster and reflects container writes back to the host filesystem, but requires act's CWD to be resolvable from the container daemon's mount namespace. Set to true on bare-metal deployments where the daemon and act share the same mount namespace. Default is true: bind-mounting is faster and reflects writes back. Set to false when act runs inside a mount-namespace boundary (e.g. a coordinator container or NixOS nspawn container) and the container daemon cannot resolve the workspace path. The no-bind path streams the checkout through the Docker API when actions/checkout runs, which correctly crosses the namespace boundary and includes .git.
  • CLI: --act-bind-workspace <ACT_BIND_WORKSPACE>
  • Value: type boolean; cardinality 1; default true; values true, false
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_ACT_JOB_CONTAINER_POLICY — Who controls the containers CI jobs run in: admin (default) or workflow. admin: jobs run in the coordinator-configured platform images with the --act-container-options spec. Workflows whose jobs declare container: or services: blocks — which act would let replace or escape the admin spec (including host mounts and unlimited resources) — are refused, publishing a failed result that explains why. workflow: trust workflow authors; act's native semantics apply and workflow-supplied container options replace the admin spec for those jobs.
  • CLI: --act-job-container-policy <ACT_JOB_CONTAINER_POLICY>
  • Value: type enum; cardinality 1; default admin; values admin, workflow
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_MAX_CONCURRENT_JOBS — Maximum number of CI jobs that may run concurrently
  • CLI: --max-concurrent-jobs <MAX_CONCURRENT_JOBS>
  • Value: type integer; cardinality 1; default 1; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: max-concurrent-jobs-positive
• NGIT_CI_MAX_QUEUED_JOBS — Maximum number of planned CI jobs that may wait in the coordinator's FIFO job queue while all job slots are busy. When the queue is full, newly planned jobs are dropped with a warning and their trigger events are left unprocessed, so relay replays and repo-state re-diffs retry them later.
  • CLI: --max-queued-jobs <MAX_QUEUED_JOBS>
  • Value: type integer; cardinality 1; default 64; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: max-queued-jobs-positive
• NGIT_CI_QUEUE_RECOVERY_WINDOW_SECS — Maximum age, in seconds, of a graceful-shutdown queue checkpoint that may be restored on startup
  • CLI: --queue-recovery-window-secs <QUEUE_RECOVERY_WINDOW_SECS>
  • Value: type duration_seconds; cardinality 1; default 600; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: queue-recovery-window-positive
• NGIT_CI_JOB_TIMEOUT_SECS — Maximum runtime for one CI job, in seconds
  • CLI: --job-timeout-secs <JOB_TIMEOUT_SECS>
  • Value: type duration_seconds; cardinality 1; default 1800; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: job-timeout-positive
• NGIT_CI_BLOSSOM_SERVERS — Comma-separated http(s) Blossom server base URLs. Empty disables all Blossom uploads and act artifact staging
  • CLI: --blossom-servers <BLOSSOM_SERVERS>
  • Value: type http_url; cardinality 0+; default empty string; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: blossom-server-url-format
• NGIT_CI_BLOSSOM_MAX_LOG_BYTES — Maximum retained per-job log bytes for Blossom upload. Longer logs are tailed with the standard truncation banner before upload
  • CLI: --blossom-max-log-bytes <BLOSSOM_MAX_LOG_BYTES>
  • Value: type byte_count; cardinality 1; default 4194304; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: blossom-max-log-bytes-positive
• NGIT_CI_BLOSSOM_MAX_ARTIFACT_BYTES — Maximum size, in bytes, of one artifact file to upload
  • CLI: --blossom-max-artifact-bytes <BLOSSOM_MAX_ARTIFACT_BYTES>
  • Value: type byte_count; cardinality 1; default 67108864; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: blossom-max-artifact-bytes-positive
• NGIT_CI_BLOSSOM_MAX_ARTIFACTS_PER_JOB — Maximum number of artifact files attached to each job result
  • CLI: --blossom-max-artifacts-per-job <BLOSSOM_MAX_ARTIFACTS_PER_JOB>
  • Value: type integer; cardinality 1; default 16; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: blossom-max-artifacts-per-job-positive
• NGIT_CI_BLOSSOM_UPLOAD_TIMEOUT_SECS — Per-blob Blossom upload timeout, in seconds
  • CLI: --blossom-upload-timeout-secs <BLOSSOM_UPLOAD_TIMEOUT_SECS>
  • Value: type duration_seconds; cardinality 1; default 60; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: blossom-upload-timeout-positive
• NGIT_CI_BLOSSOM_UPLOAD_BUDGET_SECS — Total budget for the post-run Blossom upload phase, in seconds
  • CLI: --blossom-upload-budget-secs <BLOSSOM_UPLOAD_BUDGET_SECS>
  • Value: type duration_seconds; cardinality 1; default 120; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: blossom-upload-budget-positive
• NGIT_CI_BLOSSOM_ARTIFACT_SERVER_ADDR — Optional address for act's artifact server. Empty leaves act's outbound-IP default in place
  • CLI: --blossom-artifact-server-addr <BLOSSOM_ARTIFACT_SERVER_ADDR>
  • Value: type address_string; cardinality 0–1; default empty string; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_BLOSSOM_PUBLIC_URL — Public base URL to use in published logs/artifact tags instead of the Blossom upload server URL. Useful when the upload endpoint is a loopback or Tailscale address and the published URL must be externally accessible. Only the scheme/host/port are used; any path is rejected at validation. Empty: use the upload server URL as-is
  • CLI: --blossom-public-url <BLOSSOM_PUBLIC_URL>
  • Value: type http_origin; cardinality 0–1; default empty string; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: blossom-public-url-format, blossom-public-url-origin-path
• NGIT_CI_PROCESSED_IDS_PATH — Path to the JSON file storing event ids the coordinator has already processed. Prevents duplicate CI runs across restarts when the index relay still has those events in its retention window. Defaults to .coordinator-processed-ids.json in the working directory.
  • CLI: --processed-ids-path <PROCESSED_IDS_PATH>
  • Value: type path; cardinality 1; default .coordinator-processed-ids.json; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: queue-state-and-processed-ids-distinct
• NGIT_CI_QUEUE_STATE_PATH — Path to the JSON checkpoint used to preserve unstarted queued jobs across a short graceful restart
  • CLI: --queue-state-path <QUEUE_STATE_PATH>
  • Value: type path; cardinality 1; default .coordinator-queued-jobs.json; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: queue-state-and-processed-ids-distinct
• NGIT_CI_EVENT_CACHE_DIR — Directory containing the persistent rust-nostr event cache. Backend filenames and layout are private implementation details
  • CLI: --event-cache-dir <EVENT_CACHE_DIR>
  • Value: type path; cardinality 1; default .ngit-ci-cache; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: —
• NGIT_CI_SECRET_<ALIAS>__<NAME> (pattern, secret) — Per-repository workflow secrets selected by an alias declared on a watched repository. Secret values are never accepted on argv.
  • CLI: not accepted on argv
  • Value: type repository_secret_pattern; cardinality 0+; default —; values —
  • Runtime: scope coordinator_jobs; reload source dependent
  • Rules: repository-secret-aliases-unique, repository-secret-name-format, repository-secret-name-reserved, github-read-token-format
• NGIT_CI_COORDINATOR_NSEC (secret) — Coordinator Nostr secret key. It is never accepted on argv.
  • CLI: not accepted on argv
  • Value: type nostr_secret_key; cardinality 0–1; default —; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: coordinator-key-format
• NGIT_CI_OPERATOR_BUNKER (secret) — Operator fallback NIP-46 bunker URI for sealing Nostr-provisioned secrets. It is never accepted on argv.
  • CLI: not accepted on argv
  • Value: type nip46_bunker_uri; cardinality 0–1; default —; values —
  • Runtime: scope coordinator; reload restart required
  • Rules: operator-bunker-uri-format