Record releases and checks #

View this page as Markdown

Prompt:

Connect this project's release pipeline and checks to tzTrack so we can see which fixes shipped and which still need verification.

Record a fix when its commit lands, record the build that carries it, and send each check's real result. These records let tzTrack distinguish a change that landed from one that was released and checked. They do not run your tests or deploy your application.

In every customer space, a green check supplies verification evidence only for the issue that check opened, rather than every issue in the components it covers. Read the verification result explains which fixes need a person's recheck.

What your AI tool does #

  • Reads the space's configuration and connects the project's components to release lines.
  • Adds calls to the existing landing, release and check jobs, using real commits, test evidence and build identities.
  • Reads the resulting issue history and records any verification still needed.

What you need #

  • A project with commits, a release pipeline and checks whose results the pipeline can read.
  • The project's tzTrack space and a token with owner access. Your account has owner access in its own space; a shared space's owner assigns access.
  • A secret store for the pipeline token. Never put its value in source, logs or an AI conversation.

Before your AI starts #

These steps are for your AI tool.

  • Read the project's setting file, choose its space, and call the REST API's read_space. Preserve its existing configuration.
  • Get a tzTrack token through Mint a token: from the signed-in session, request the tztrack grant and a label identifying the pipeline. Give the person the returned token-claim command to run in their own terminal into the secret store. Save the secret as TZTRACK_TOKEN; no token value passes through your tool.
  • Read the REST API. This guide calls land, deploy, ship and check over that API. These release-recording acts are not tzTrack MCP tools. Set components and release lines with the REST API's configure as well: the configure MCP tool changes only the background-review setting.
  • Check what the existing integration already records. The platform already records builds for hosted applications at deploy, promote and rollback; add no duplicate calls.

Steps #

1. Set the components and release lines #

Call the REST API's read_space before its configure. For each configuration member you change, send its complete list: a named list replaces that member, and omitted members stay as they are.

Choose a release line for each independently released part of the project, and map each component's paths to it:

Configuration What to set
release_lines Declare each line's name and kind: product or client. Omitted kind means product. The REST reference links the complete field types and limits.
components Give each component a name, its paths in globs, a declared release_line, and its exposure source. Keep existing aliases and about when replacing an entry.

Choose checks for a component your pipeline's checks cover, and none otherwise. A green check supplies an exposure only on that check's own issue; expect the verification limit in step 5. Choosing an exposure source alone creates no evidence.

With no components declared, the starter components have no path patterns, use the landing line and have exposure none. A fix in such a component closes done at landing, so release records do not start a verification watch for it. Configure the component before relying on that watch.

2. Send records from the pipeline #

Each call is an HTTPS POST to https://tztrack.turnzero.ai/v1/<act>, with a JSON body and the tzTrack token as its bearer credential. Set TZTRACK_SPACE to the chosen space's identifier so a job always names its space explicitly. This Node.js helper reads both settings without printing them:

// record-tztrack.mjs
import { readFile } from 'node:fs/promises';

const [act, file] = process.argv.slice(2);
if (!['land', 'deploy', 'ship', 'check'].includes(act) || !file) {
  throw new Error('Use: node record-tztrack.mjs <land|deploy|ship|check> <body.json>');
}
if (!process.env.TZTRACK_TOKEN || !process.env.TZTRACK_SPACE) {
  throw new Error('Set TZTRACK_TOKEN and TZTRACK_SPACE in the pipeline settings');
}
const body = JSON.parse(await readFile(file, 'utf8'));
const response = await fetch(`https://tztrack.turnzero.ai/v1/${act}`, {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.TZTRACK_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ ...body, space: process.env.TZTRACK_SPACE }),
});
if (!response.ok) {
  const refusal = await response.json().catch(() => ({}));
  throw new Error(`tzTrack refused ${act}: ${refusal.error ?? 'HTTP error'} (${response.status})`);
}
console.log(`tzTrack recorded ${act}`);

Create each body from the job's actual inputs, then run the helper with its file, for example node record-tztrack.mjs land landing.json. The following steps describe those bodies. The REST reference gives their complete fields and answers.

For an act that accepts key, derive a stable key from that event, so retrying the same event records no duplicate. Keep the same key on a retry; do not generate a new one for each attempt.

3. Record the landed commit and its release #

After a commit lands, call land once for each issue it fixes, narrows, resolves or reverts:

Member What the landing job supplies
issue The issue's number or identifier.
commit The landed commit carrying the code change.
trailer fixes, narrows, resolves or revert. A docs issue, gap, question, task or idea uses resolves.
test, proof For fixes or narrows on a bug or friction, the regression test and its actual proof: base, the test file's SHA-256 hash, and result (proved, unverified or untestable). Supply accepted_by and reason only for an accepted untestable result. Never invent proof to make the call pass.
component, remainder, key The affected component, any remainder the narrowing leaves, and the event's stable key, as applicable.

A bug or friction with a report from test, beta, field or platform moves to fixed when a fix is recorded. One with only workspace or person reports closes done, as does a fix whose component has exposure none. An AI's own reports through the MCP tools have origin workspace. resolves closes completed work done.

Where the platform or your existing integration does not already record the build, call deploy:

  • Give release_line, version, environment and its commit.
  • Give order, a whole number greater than every earlier build's order on that line and environment.
  • Set live: true when that build is actually live. On withdrawal or rollback, record withdrawn: true for the withdrawn build; the fixed issues it carried and issues it verified reopen.
  • Repeating an existing build updates live and withdrawn only. A new version needs its own build record.

Then call ship for the recorded build. Its build is { release_line, version, environment }; landings lists the landed code-change commits carried in that build, selected from its actual range for the component on that release line. The reference gives the full ship contract, including landings recorded on records-only commits. Make one call per build. Unknown commits are ignored, so ship cannot replace a missing land record. If your integration already sends ship, keep those calls rather than adding duplicates.

Read the issue's landings and history to confirm both landed and shipped. A landing starts its verification watch only when it ships on the component's line.

4. Record every check result #

Call check after the check has finished, whether it passed or failed. Supply:

  • check: a stable check name;
  • covers: the components and actions it actually checks;
  • result: green or red;
  • builds: the actual { release_line, version, environment } entries checked;
  • cause: null, harness or estate, when known;
  • the applicable component, evidence and event key.

A red on the check's first run, or its first red after a green, opens an episode. Further reds that reach the check thresholds open an issue of origin test, named by the check's key. Read those thresholds in read_space: they are fixed for customer spaces. Keep the check name stable across runs so later results update that episode.

A green check on a live build carrying the fix can record an exposure on that check's own issue. It does not supply exposures to every issue whose component appears in covers.

5. Read the verification result #

Read the issue after the records arrive. Check its landings, each landing's shipped map, and the history's landed, shipped and exposed entries. An exposure counts only when its source matches the component's configured source and its build is live, not withdrawn, and at or beyond the shipping build's order.

The daily sweep closes the issue verified after three qualifying exposures, unless a report concerning the fix still waits to be read. read_space shows exposures_to_verify: 3 and watch_cap_days: 14. These verification constants and the check thresholds are fixed for customer spaces; the REST API's configure refuses changes to them.

With too little evidence after 14 days, it stays fixed and gains recheck. A landing that never ships also gains recheck after 14 days. List those issues with label: "recheck" and state: "fixed", then have the responsible person examine the remaining evidence.

In a customer space, a field- or beta-reported fix does not acquire exposures merely because a check covering its component is green. Hosting the application on Turn Zero Cloud does not add an exposure for that fix. With these REST records alone, it ships and is watched, then needs that recheck. An owner can close it done with a resolution explaining what was actually checked. The REST API serves no expose act for a pipeline to call.

Expected result #

Each fix has its landed commit, each release has a build and its shipped landings, and each check has its actual result. The issue history shows the evidence received. Eligible fixes close verified at the daily sweep; those still needing evidence remain fixed and may require a person's recheck.

Refusals #

Read the REST API restrictions and Refusals for the full list.

Refusal Status Cause Remedy
credential_required or credential_refused 401 The bearer token is missing or not accepted. Check the pipeline's secret binding and obtain a valid tzTrack token without printing its value.
grant_required 403 The token lacks the access the act requires. Use owner access for these recording acts; do not retry expose through this API.
invalid_request 400 A field, component, release line or proof is invalid. Read the refusal and correct the body from the actual configuration and evidence.
build_not_found 404 ship named a build not yet recorded. Record the build with deploy first.
state_conflict 409 fixes or narrows was used on a docs issue, gap, question, task or idea. Use resolves for completed work of those kinds.
default_space_needed or default_space_changed 409 A request omitted the space and cannot safely choose it. Name the intended space explicitly, as the helper does.