Skip to main content

Publish build results

Publication needs an onboarded repository publisher role, AWS temporary credentials, and permission to upload beneath its designated S3 prefix. Ask the Vulcan operator to configure these permissions before integrating a new producer. Publication is an API workflow; integrators never need database access.

Run lifecycle​

  1. Create a run with POST /v1/runs. Supply the run type, source and environment identity required by CreateRun in the reference. Retain the returned run ID for every later step.
  2. Register inputs and parameters with PUT /v1/runs/{run_id}/inputs/{name} and /parameters. Record canonical input identity, checksums, environment, and parameters so another client can understand or resolve this build.
  3. Upload artifact bytes to S3 using the publisher's permitted bucket/prefix. The registry API registers metadata; it is not an artifact upload endpoint.
  4. Register each artifact with PUT /v1/runs/{run_id}/artifacts/{name}, including its exact S3 version, size, and SHA-256 per the schema. The writer verifies the object; an unverified upload is not a published artifact.
  5. Record evidence with the test-result and measurement endpoints. Preserve attempt identities and use the defined metric units/schema.
  6. Finalize with POST /v1/runs/{run_id}/finalize, setting the appropriate terminal status. A completed run is immutable; complete all child writes first.
  7. Verify publication using the authenticated /publication-status route. Consumers can then discover eligible results through public reads for an allowlisted repository. A failed or incomplete run is not a reusable success.

Request bodies vary by run type. Use the reference schemas rather than inventing a generic payload or copying credentials from an existing workflow.

Idempotency and recovery​

Mutation requests require a stable repository-scoped Idempotency-Key. Reuse both the same key and identical canonical payload when retrying the same logical operation. A different operation needs its own key. A key reused with changed content returns 409; run creation returns 201 initially and 200 on replay. Retain keys and run IDs across workflow reruns so a network timeout does not cause duplicate publications. Check publication state before retrying an uncertain finalization.

Sign every retry with fresh SigV4 headers, keeping the idempotency key and body unchanged. Bound retries with backoff for transient network/service failures; correct authentication or validation failures before resubmitting.

Publish a model catalog​

A model catalog is a complete immutable snapshot identified by the full source commit (catalog_revision). Finish the referenced compilation runs first; each build must match its compile fingerprint. Publish the complete model metadata, taxonomy, and build references through PUT /v1/repositories/{organization}/{repository}/catalogs/{revision}. The writer validates the snapshot and advances the branch's current pointer atomically. Omitting a model from the next snapshot removes it from the current catalog without rewriting historical snapshots.

For incremental build progress, the catalog snapshot endpoint supports pending build groups as described in the reference. Keep pending and completed build identities consistent. A taxonomy checksum is an integrity check, not an independent taxonomy version.

Finalize and select a deployment candidate​

When an integration assembles a deployment from multiple runs, create a candidate with POST /v1/repositories/{organization}/{repository}/deployments, retain its deployment_id, and attach each run through PUT /v1/repositories/{organization}/{repository}/deployments/{deployment_id}/runs/{run_id}. Finalize it using the candidate /finalize endpoint after the required native manifests and dependencies are available. Read the authenticated deployment GET to inspect its state. A candidate is separate from a run or catalog snapshot.

A publisher can select a protected, finalized candidate for its feature branch using POST /v1/repositories/{organization}/{repository}/branch-deployments. Supply the current catalog digest as expected_snapshot: stale selections return a conflict. This route excludes Develop, Main, and master; it does not approve or copy artifacts.

To promote an existing candidate to Develop, create a request through the repository /promotions endpoint and retain promotion_id. A separate scoped approver role must approve or reject it. Publishers can inspect or cancel a pending request; cancellation does not undo a completed promotion. Approval checks the reviewed target snapshot and candidate dependencies atomically. If the target snapshot changes, obtain a new request and review rather than silently approving changed content. Pending holds expire after seven days. All candidate/promotion operations, including status GETs, require IAM. Use the reference schemas for exact contract, snapshot, and review fields.

Lifecycle and deletion​

New successful equivalent compilations supersede older successes. Superseded runs stop appearing in discovery/resolution, and their exact object versions are eligible for cleanup after the recovery window. Do not treat signed URLs or old discovery results as permanent retention guarantees.

Branch purge is destructive and operational: queue it only for an intentionally deleted branch, retain its job ID, and poll the authenticated purge-job endpoint. A queued response is not completion. A tombstone blocks new publication while cleanup proceeds. A recreated branch must be restored before publishing again; restore is rejected while the earlier purge is incomplete. Automatic branch reconciliation uses a separate authorized identity.