Release input document

The input documentCopy Anchor Link

Every evaluation gets an input document with version set to prodgator.input/v1 and subject set to release. Release and pull request inputs share a core (version, subject, evaluatedAt, repository, commitSha, commitSeenAt, commitAgeSeconds, actor, checks, labels, attestations, workflows, security, approvals, aiAssisted); the fields below this point are the release subject's own section, plus that shared core:

{
  "version": "prodgator.input/v1",
  "subject": "release",
  "evaluatedAt": "2026-09-28T15:30:00.000Z",
  "repository": { "name": "acme/api", "id": "365246789" },
  "commitSha": "4f2c1e0",
  "commitSeenAt": "2026-09-28T15:28:00.000Z",
  "commitAgeSeconds": 120,
  "actor": { "login": "octocat", "providerUserId": "583231", "prodgatorUserId": "user_01H...", "groups": ["grp_release"], "isBot": false },
  "checks": [{ "name": "test", "source": "check_run", "app": null, "status": "completed", "conclusion": "success", "url": null }],
  "labels": ["release"],
  "security": null,
  "release": {
    "deploymentId": "d_123",
    "provider": "github",
    "repository": "acme/api",
    "environment": "production",
    "workflow": "Deploy",
    "runId": 123456789,
    "commitSha": "4f2c1e0",
    "branch": "main",
    "releaseName": null,
    "actor": { "login": "octocat", "providerUserId": "583231", "prodgatorUserId": "user_01H...", "groups": ["grp_release"], "isBot": false }
  },
  "github": {
    "branch": "main",
    "checks": [{ "name": "test", "status": "completed", "conclusion": "success" }],
    "labels": ["release"],
    "commitMessage": "Bump version",
    "prTitle": "Release 1.4.0"
  },
  "approvals": [
    {
      "prodgatorUserId": "user_01H...",
      "email": "jane@example.com",
      "groups": ["group-id"],
      "decision": "approved",
      "at": "2026-09-28T15:20:00.000Z",
      "providerLogin": "jane",
      "commitSha": null
    }
  ],
  "aiAssisted": { "value": true, "tools": ["claude"], "signals": ["pull_request"], "current": true },
  "settings": { "selfApproval": false, "reviewerForwarding": true },
  "attestations": [
    {
      "id": "3f1c...",
      "kind": "coverage",
      "name": "unit",
      "status": "pass",
      "trusted": true,
      "workflowRef": "acme/api/.github/workflows/ci.yml@refs/heads/main",
      "jobWorkflowRef": "acme/platform/.github/workflows/build.yml@refs/tags/v2",
      "workflowSha": "4f2c1e0b7a9d3c5e1f8a6b4d2c0e9f7a5b3d1c8e",
      "jobWorkflowSha": "1b9e4c7d2f0a8e6b5c3d1f9a7e5c3b1d9f7a5e3c",
      "eventName": "push",
      "runId": "123456700",
      "attempt": 1,
      "job": "test",
      "createdAt": "2026-09-28T15:10:00.000Z",
      "data": { "lines": 87.5, "branches": null, "functions": null, "threshold": 80 }
    }
  ],
  "workflows": {
    "supported": true,
    "known": true,
    "settled": true,
    "runs": [{ "runId": "123456789", "workflow": "Deploy", "finished": false }],
    "referenced": [
      {
        "path": "acme/platform/.github/workflows/build.yml",
        "ref": "refs/tags/v2",
        "sha": "1b9e4c7d2f0a8e6b5c3d1f9a7e5c3b1d9f7a5e3c",
        "runId": "123456789",
        "workflow": "Deploy"
      }
    ]
  },
  "tickets": [],
  "webhooks": []
}

• subject, repository, commitSha, actor, checks, labels and security are the shared core; actor is the same object as release.actor. checks and labels repeat github.checks and github.labels in the shared shape (Rego shared between subjects reads these; release-only Rego can keep reading github.*).
• github is null when Prodgator could not read facts from GitHub; checks and labels are then null too.
• commitSeenAt is when the deployment was created, and commitAgeSeconds the whole number of seconds from then to evaluatedAt. Both are null when unknown. The Required checks rule counts its wait for checks to start from here.
• release.actor.prodgatorUserId is null when the person who started the deployment has not linked their GitHub account in Prodgator.
• actor.groups lists the approver group ids of that linked account (empty when not linked), and actor.isBot is true for a GitHub account of type Bot or a login ending in [bot]. Inputs stored before these fields existed lack them. The Allowed actors rule reads them.
• approvals holds each person's latest approval or rejection given in Prodgator, with the approver groups they belong to. commitSha is always null here, since a release approval is per deployment, not per commit; it is set for a pull request approval.
• security is reserved for findings introduced by the change and is null until that ships.
• aiAssisted says whether the release ships AI-assisted changes; it is null when your plan does not include AI impact (Business and Enterprise), no policy on the release has an AI-assisted changes rule, custom rules or Rego (it is only read then), or Prodgator could not read the release's history. value is true when it does. tools lists the AI tools found (claude, copilot, cursor, devin, codex, gemini, jules, aider, or other). signals lists the kinds of evidence: pull_request (a shipped pull request was AI-assisted), commit_trailer (a shipped commit has an AI trailer) and label (the labels of the pull request that produced the commit, read only when the history could not be). current is true once the release's changes were read. The AI-assisted changes rule reads it.
• attestations holds the attestations sent by the Prodgator report action for release.commitSha, from any run and attempt, oldest first. Only the newest per kind, name, workflow file, reusable workflow file and trusted value is included.
• self_reported_attestations holds the results sent through Any CI, in the same shape as attestations, each with trusted set to false and selfReported set to true. It is present only when a rule of the policy has the Count self-reported results from other CI option on, and it is null when Prodgator could not read them. Stored policies that do not read it never see these results.
• In each attestation, workflowRef and workflowSha name the workflow file of the run that sent it and the commit of that file (GitHub's workflow_ref and workflow_sha token claims). When the job ran inside a reusable workflow, jobWorkflowRef and jobWorkflowSha name that reusable workflow and its commit (job_workflow_ref and job_workflow_sha); otherwise they are null. GitLab attestations carry the pipeline configuration's commit (ci_config_sha) as workflowSha; Bitbucket attestations have null for both SHAs, and so do attestations sent before Prodgator stored them.
• workflows lists the reusable workflows the deployment's GitHub Actions run called, for the Required reusable workflow rule. Its fields are described in the pull request input document. For a release, runs holds the deployment's run and runId is GitHub's run id. known is false while Prodgator has not recorded the run's calls, and supported is false for GitLab and Bitbucket deployments. It is null when Prodgator could not read the run. data has the fields listed in Run reports. It is [] without a commit SHA and null when Prodgator could not read attestations.
• tickets and webhooks are reserved and always empty for now.

Pull request policies read the same core plus their own section. See Pull request input document.

Release riskCopy Anchor Link

Release inputs carry releaseRisk: { level, generatedAt, deploymentId, reused }, or null when there is no rating for the deployment. level is low, medium or high (the highest rating the deployment received, so regenerating cannot lower it), generatedAt is when the rating was written, deploymentId is the deployment it was written for, and reused is true when it came from another deployment with the same code and checks. The summary text is never included. The Release risk rule reads it; treat null as unknown, never as low risk.

releaseRiskState says where the rating stands: ready (releaseRisk is set), generating (being written, or it could not be read just now, so it may still arrive) or missing (it will not come without someone acting, or no policy reads it). Wait while it is generating rather than failing.

Change, lineage and evidenceCopy Anchor Link

Release inputs also carry change, lineage and evidence. These are null without release provenance in the plan (Business and above), or when the required facts cannot be read. change can also be null when the commit has no landed change record. Never interpret null as a verified change or a passed promotion.

The top-level lineageUnavailable boolean is true when a change or lineage read failed. When lineage is null, promotion rules use it to distinguish a read failure from release provenance missing from the plan.

ChangeCopy Anchor Link

To require a verified change with no bypass, use the Verified change form rule. It reads these fields, handles missing or unreadable data, and links failures to Provenance.

LineageCopy Anchor Link

Each hop includes seq, kind, branch, environment, protectedEnvironment, pullRequest (number, source and target branches, method and optional fork: true for a fork pull request), commitSha, tree, at, status (identical, changed, unknown), reason, samePatch, changedPaths, changedPathCount, verdict, stepOver, backMerge and targetOnly. pullRequest.fork marks a hop whose source branch cannot meet a branch step; a verified fork pull request can still land a commit on its target branch. samePatch can be true, false, unknown or null. targetOnly contains changeIds and allVerified when known.

Both trace shapes expose source, onPath, steps, followed, followedExceptVerifiedChanges, skipped, outOfOrder, offPath and extraChanges. source is policy, repository or organization. Policy traces always set onPath; fallback traces set it to false for an off-path release and can omit it for an on-path release. Each step carries branch, environment (and gate for a policy step), status, change ID, merge SHA, run ID and status, deployment ID and status, and time. Status is current, passed, failed, pending, missing, skipped, out_of_order or unknown.

At evaluation, distinct policy paths are traced against stored lineage. Keys have the form p plus 24 hexadecimal characters derived from the canonical steps. Generated Rego refers only to input.lineage.paths[key]; it does not embed customer branch, environment or gate text. At most five distinct policy paths are traced per evaluation. A path beyond that limit has no trace and its rule returns error.

EvidenceCopy Anchor Link

evidence.hops contains one aggregate per hop with its seq. evidence.released covers the release backward until the first changed or unknown hop. evidence.chain covers the whole path, including changed content. All aggregates have:

Only trusted reports count toward tests, coverage and findings. Sources are deduplicated. Coverage takes the minimum; findings take the highest count per severity across distinct content groups. Zero counts without a report or scan do not prove evidence exists.

Example: UAT ran the released codeCopy Anchor Link

This adapts the promotion example to reject missing, incomplete and truncated lineage. It waits while collection is pending and requires UAT to have unchanged code and passing tests.

package prodgator.policy

lineage := object.get(input, "lineage", null)
lin := lineage if is_object(lineage) else := {}
uat := [e | some e in object.get(lin, "environments", []); lower(e.name) == "uat"]

status := "pending" if object.get(lin, "state", null) == "pending"
else := "pass" if {
  lin.state == "ready"
  lin.complete == true
  lin.truncated == false
  count(uat) == 1
  uat[0].unchanged == true
  uat[0].tested == true
}
else := "fail"

results := [{
  "rule": "uat_unchanged",
  "status": status,
  "blocking": true,
  "reason": "UAT must run the released code with passing tests",
  "evidence": {"uat": uat}
}]