Vetrix Docs

CI/CD architecture

Internal-design reference for the Vetrix CI/CD subsystem: how a pipeline job is isolated and executed, how its output and artifacts are captured, and how the platform gates what a run is permitted to do. These pages describe implementation contracts — table shapes, JSON schemas, reason strings, endpoint paths, and the packages that own each behaviour — and are written for readers reasoning about or changing the subsystem, not for pipeline authors following a how-to.

Each page states what ships today and, where a surface is only partly wired, which parts are stable contracts and which are not yet reachable.

Run execution and artifacts

How a job is placed on a runner, executed under isolation, retried, and what it leaves behind.

  • Firecracker runner executor — The ephemeral microVM executor used for untrusted workloads: which conditions force a job onto a Firecracker runner group, the per-job boot/execute/teardown lifecycle and its boot budget, rootfs image allowlisting, the reduced network posture applied to fork merge-request refs, CPU/memory caps, and the executor metrics.
  • Single-step retry — Re-running one failed step or matrix cell instead of the whole pipeline: the retry: YAML block and its parse-time validation, the pure PlanRetry decision function with its stable reason strings, the guardrail that stops a fork merge-request retry from materialising environment-scoped secrets, and the downstream re-evaluation comparator.
  • Job log store — Durable job output: the broker/persistent-writer/ chunk-store pipeline, the job_log_chunks table and the indexes behind it, byte-offset Last-Event-ID resume with switch-over from historical backfill to the live stream, the retention sweep, and the redactor placed ahead of the writer so secret values never reach storage.
  • coverage-summary.json artifact — The well-known coverage-artifact filename: how the runner auto-collects it from the workspace root without an artifacts.paths declaration, the schema-v1 field reference and what the collect-time validator rejects, its compatibility guarantees, how a merged unit plus integration profile is produced by a single job, and the endpoint the coverage report reads.

Policy, gating, and supply chain

What a run is allowed to do, what it must prove, and what it may credential itself with.

  • Policy gates — Operator-defined gates evaluated at workflow-schedule time: the policy_gates table, warn versus block enforcement, the instance/org/repo/environment scope ladder that a narrower gate cannot bypass, the native policy language and its parse-time sandbox and evaluation budget, and the reusable-workflow resolver's nesting limit and input type-checking.
  • Pipeline branch protection — The required-pipeline branch gate: the per-job allow_failure flag and how hard versus soft failure is derived without adding a job state, the computed per-commit required-pipeline verdict, why it is recomputed rather than stored, and the three enforcement surfaces — strict on merge, lenient on merge-request open, and fail-open on push — with the audit events each emits.
  • OIDC federation for workflow jobs — Minting short-lived signed tokens that jobs exchange for credentials at an external identity provider instead of holding long-lived cloud secrets: wildcard subject patterns and how the most specific trust policy is selected, the token and trust-policy endpoints, the request and claim shapes, and the safety invariants covering fork merge-requests, TTL clamping, and reuse as a session token.
  • SBOM attestations — The software-bill-of-materials attestation subsystem: which SBOM document formats the platform accepts and how an unsupported one is refused, the artifact-scoped attestation endpoints used to record and list an SBOM and the permissions they require, how payloads are held outside the attestation row, and the access-control treatment of SBOM content.