Vetrix Docs

CI/CD

Administrator documentation for the Vetrix CI/CD subsystem: the instance-wide settings that govern whether and how jobs run, and the deployment wiring a runner or containerized worker needs before jobs can launch containers, receive per-branch variables, and hand artifacts back. Use the instance-configuration pages for policy questions ("what caps a job?") and the runner and worker pages for deployment questions ("why did every job fail at once?").

Instance configuration

  • CI/CD Configuration — The instance-level ci.* runtime settings (ci.enabled, ci.max_job_timeout, ci.max_concurrency, the ci.allowed_images image prefix allowlist, and ci.artifact_retention_days), the admin runner registration and deletion endpoints, blob-directory artifact storage and manual purge, queue depth via the admin health endpoint, and how to pause dispatch without removing runners.
  • Pipeline Variables — Per-branch variables set from Pipelines → Environment configuration: AES-256-GCM encrypted at rest, write-only through the UI and API, excluded from fork-originated PR runs, always masked in job logs, and audited on each decrypt. Also covers the worker-side prerequisites (a wired resolver plus a SECRET_ENC_KEY matching the server's), the fail-open behaviour when the key is absent, and the resolution precedence in which a branch variable overrides committed vetrix-ci.yml.

Runner and worker deployment

  • CI Runners — Registering a runner and its one-time token, starting vetrix-runner by flag, environment variable, or vetrix-runner.toml, the offline/idle/busy lifecycle and its 30-second heartbeat and 60-second offline threshold, the default Docker executor and its privileged setting, a systemd unit template, and how to scale by concurrency or additional runners.
  • Worker Docker-Socket Access — Why the containerized worker must carry the socket's numeric owning GID as a supplementary group via group_add, how to read that GID from the host, and why the user: pin must not be removed to work around the permission error. Diagnoses the case where every job — including a trivial hello-world — fails within a second at exit_code=126 with a Docker socket permission denial, and distinguishes it from jobs that never leave pending.
  • Runner Artifact Collection — Why declared artifacts.paths collect zero files when the worker has no host-side per-job workspace, how to wire RUNNER_WORKSPACE_DIR plus a writable bind mount owned by the worker's runtime identity, the three collection WARN lines in the worker error log and what each one means, that globs resolve relative to the workspace root and directories are skipped, and the end-to-end verification that an artifact becomes retrievable.