chant components

Synopsis

chant components release <env> --component <name> --digest <sha256:...>
                                [--git-sha <sha>] [--run-id <id>] [--actor <name>] [--json]
chant components status [env] [--live] [--json] [--compare-to <env>]
chant components export <env> --component <name> [--digest <manifestDigest>]
                                -o <dir> [--json]

Description

chant components holds the release ledger, status surface, and build-archive export for component deploys: the recorded half of build & deploy observability. See Observability for the conceptual model. The release ledger lives on the same chant/lifecycle orphan branch chant lifecycle snapshots already use, at <env>/releases.jsonl — one immutable JSON line per recorded deploy.

components release below is the standalone, explicit way to append a record. chant run --components auto-emits one on every successful deploy, so most projects never need to call components release directly — it remains useful for CI compositions and Verify phases outside chant run’s own execution.

Subcommands

components release <env>

Append one immutable release record: (component, env, artifact digest, git sha, run id, timestamp, actor).

chant components release prod \
  --component search-service \
  --digest sha256:9fae3d7c... \
  --git-sha "$(git rev-parse HEAD)" \
  --run-id "$GITHUB_RUN_ID" \
  --actor "$GITHUB_ACTOR"

Flag	Meaning
--component <name>	Required. The component this deploy released.
--digest <sha256:...>	Required. The promoted artifact’s content digest — the join key with the build archive/ledger.
--git-sha <sha>	Git commit the deploy was built from. Defaults to the current HEAD.
--run-id <id>	Orchestrator/CI run identifier. Defaults to $GITHUB_RUN_ID or $CI_PIPELINE_ID, else a locally generated id.
--actor <name>	Who/what triggered the deploy. Defaults to $GITHUB_ACTOR, $GITLAB_USER_LOGIN, or $USER — but must resolve to something; an unattributed record fails rather than falls back to a placeholder.
--json	Print the recorded record as JSON instead of a human summary.

The timestamp is always a real new Date() taken by the CLI at record time — never threaded in from elsewhere, and never re-derived later. A record is never edited or replaced: recording again appends a new line.

Pushes to the remote afterward using the same --force-with-lease protocol snapshots use; a concurrent write from another operator is rejected with a recovery hint rather than silently overwritten.

components status [env]

Reconcile the release ledger against live truth (when --live is passed) or report the ledger alone.

chant components status prod                       # ledger only — no live query
chant components status prod --live                 # reconcile against live + ownership
chant components status prod --live --json           # stable JSON contract
chant components status prod --compare-to staging    # cross-env digest comparison
chant components status                              # every environment with release records

Without --live, every recorded component reports unknown reconciliation — the ledger alone can’t confirm live state. With --live, chant components status reuses the same ownership-aware classification lifecycle plan already computes (buildChangeSet) to produce one of:

Reconciliation	Meaning
reconciled	Recorded, and live evidence confirms the component is present and chant-owned.
unrecorded	Live and owned, but no release record exists — deployed outside the recorded path.
stale	Recorded, but nothing observed live now.
drifted	Recorded, but live configuration has drifted since (mirrors lifecycle plan’s update).
unknown	No live evidence requested.

--compare-to <env> answers “which build is in <env>, and is it the one tested in <compare-to>” as a single query, per component:

chant components status prod --compare-to staging --json

{
  "rows": [ /* ... */ ],
  "comparisons": [
    { "component": "search-service", "envA": "prod", "envB": "staging", "digestA": "sha256:9fae3d...", "digestB": "sha256:9fae3d...", "same": true }
  ]
}

Flag	Meaning
--live	Query lexicon plugins’ describeResources() now and reconcile against ownership + drift, instead of reporting the ledger alone.
--json	Emit a stable array of rows (or { rows, comparisons } with --compare-to).
--compare-to <env>	Cross-check the requested env’s recorded digest against another environment’s, per component.

components export <env>

Materialize a persisted build archive manifest to a portable, downloadable directory: every image/template/asset/sbom entry copied byte-for-byte from where the build that produced it left it on disk (its archive-relative path, resolved against the current working directory) into -o <dir>, plus a self-describing manifest.json alongside them. No re-synthesis — it never regenerates content, only copies what a prior chant build/run --components already produced, so the export is byte-identical to what was built (promote-by-digest holds).

chant components export prod --component search-service -o ./dist/search-service
chant components export --digest sha256:9fae3d7c... -o ./dist/search-service --json

Manifest resolution:

• --digest <manifestDigest> reads the manifest directly, independent of any environment or release record.
• Without --digest, resolves “the manifest behind this component’s most recent successful run” in <env>: the latest release record’s own manifestDigest when one was recorded, else a reverse lookup by its promoted artifact digest — the same join chant components status performs.

Flag	Meaning
--component <name>	Required unless --digest is given. Which component’s most recent recorded build to export.
--digest <manifestDigest>	Export this build archive manifest directly, bypassing environment/component resolution.
-o, --output <dir>	Required. Directory the archive is materialized into.
--json	Emit a structured per-entry summary instead of a human-readable list.

A source file missing on disk (the build ran somewhere else, or its output was since cleaned) is reported per entry, and the command exits non-zero — an incomplete export is never mistaken for a complete one. Run it from the same checkout the build that produced the manifest ran in.

{
  "component": "search-service",
  "manifestDigest": "sha256:9fae3d...",
  "outDir": "/abs/path/dist/search-service",
  "entries": [
    { "kind": "template", "path": "search.template.json", "digest": "sha256:...", "status": "materialized" },
    { "kind": "image", "path": "dist/app.tar", "digest": "sha256:...", "status": "materialized" }
  ]
}

Exit Codes

Code	Meaning
0	Success
1	Error (missing required flags, unresolvable actor, concurrent ledger write, no manifest found, an export entry missing on disk)

See Also

• Observability — the release ledger, build-ledger referrer discovery, and the reconciliation model this command implements.
• chant lifecycle — snapshots, diff --live, and plan, whose ownership/drift classification components status --live reuses.
• Build Archive — the content-addressed manifest and digest identity the release ledger joins against, and what components export materializes.