Configuration reference

gcit reads a TOML configuration file. The default path depends on who is running gcit and which subcommand is invoked.

Default config path

When --config is not passed, the default depends on the running euid and subcommand:

• gcit install --user / gcit uninstall --user always resolve to the user-scope path.
• For any other subcommand invoked by a non-root euid, gcit defaults to $XDG_CONFIG_HOME/gcit/config.toml (or $HOME/.config/gcit/config.toml when $XDG_CONFIG_HOME is unset). A non-root shell running gcit run --foreground, gcit check, or gcit status without --config reads the operator’s user-scope config rather than the system one.
• Root invocations without --config use the bottom default /etc/gcit/config.toml.
• An explicit --config always wins regardless of euid or scope.

Top-level tables

A config is rejected at load time if the flow list is empty.

[poll]

Poll defaults applied to every flow unless the flow overrides them under [flow.poll].

Effective interval has a 15-second floor after jitter is applied: interval = base * (1 + sample * jitter) where sample is uniform in [-1, +1). Values outside the documented jitter range are clamped at runtime, but the validator still rejects out-of-range values at config load.

Cooldown bounds dispatch frequency. After a trigger acceptance, subsequent SHA-diff observations within cooldown are suppressed. The most recent SHA at the end of the window is dispatched when the cooldown expires. Set cooldown = "0s" to opt out.

[log]

[http]

[[flow]]

A flow is a (source, action, destinations) triple plus optional poll overrides. Each flow runs as an independent task tree under the supervisor.

[flow.source]

The git side of the flow — what gcit polls.

The polling strategy is auto-detected from url. See Polling strategies for the dispatch rules.

[flow.action]

The dispatch side of the flow — what gcit fires when the source SHA changes.

The only supported kind in v1 is github_workflow_dispatch.

Each inputs value is a handlebars template that renders against the same namespace as notifier templates — see Templates below. gcit also injects gcit_run_id into the rendered inputs payload at dispatch time so the resulting GitHub Actions run can be correlated back to gcit. See Polling strategies for the correlation contract.

[[flow.destination]]

Each flow can attach zero or more destinations. The kind discriminator selects the variant.

kind = "discord_webhook"

kind = "local_mail"

local_mail requires a system-scope install (gcit install --system); gcit install --user rejects any config with local_mail destinations.

FireEvent values

fire_on accepts these string values (snake_case):

[flow.poll] (per-flow overrides)

Same fields as [poll]. Any field not set falls back to the top-level default; if the top-level default is also unset, gcit uses the strategy’s built-in default (60s / 60s / 5m for GithubApi / Grokmirror / LsRemote).

Templates

Notification messages, dispatch input values, and Discord embed fields are rendered via handlebars in strict mode (set_strict_mode(true)). Every variable must resolve or rendering fails. Block helpers (each, with, if, unless, lookup, log, raw) are deregistered, so templates are leaf-only substitutions; comparison helpers (eq, ne, gt, …) and len remain available.

The escape function is replaced with handlebars::no_escape so plain-text outputs (mbox bodies, Discord embed leaves) are NOT HTML-encoded — Discord renders the result as markdown, mbox renders as plain text.

Variables are namespaced. Bare names like {{flow}} or {{gcit_run_id}} are rejected at config load.

Available keys

The following keys are available in every template (run-start, run-complete, mbox subject/body, Discord title/description/ collapsed_summary, dispatch [action.inputs] values):

Per-job-only keys

Discord field_name and field_value templates render once per job and additionally have access to:

{{job.*}} is not available on title, description, or collapsed_summary templates — they render once per run, not per job. The config validator’s probe context supplies stubs for every documented job key so gcit check and gcit validate-template accept templates that reference {{job.*}} in field_name or field_value. The notification path supplies the real per-job data when iterating.

Strict-mode pitfalls

• A typo in any key path (e.g. {{source.shaa}}) is rejected at config load — gcit check shows the exact line.
• Untrusted DATA values (sha, ref names, run conclusion strings, job names) render as inert text and cannot be re-interpreted as template fragments.

Reload behavior

On SIGHUP (or gcit reload), the supervisor diffs each flow against its previous shape. Flows whose config is unchanged keep their poll/dispatcher pair, credential resources, and rate-limit state — any in-flight run monitor stays attached and the per-credential rate-limit poller keeps refreshing without interruption. Credential file rotation takes effect only when no kept-alive flow still references the credential id. As long as any unchanged flow holds a credential, every flow using it continues with the previously-resolved token. If rotating because the old token was compromised, restart the daemon (systemctl restart gcit) rather than SIGHUP to ensure all flows use the new token immediately. Changed and removed flows are cancelled cleanly and the new generation starts a fresh poll cycle.