Releases and migration safety for agents

This reference extends https://app.tokay.io/llms.txt with release and migration safety actions for AI agents. Use these actions only when the user explicitly asks or a named readiness action requires them.

Last updated August 10, 2026

AI agent? Start with llms.txt.

The release model

• Tokay rehearses every managed database migration against a disposable clone of the production data before anything touches production. The evidence from that rehearsal, not the SQL text, is what release policy judges.
• Each release execution provides two kinds of evidence. impactAssessment contains observed facts, including schema diffs and the policy result in planRollup. releaseAnalysis contains the AI verdicts. liveSafe evaluates whether the current code can use the migrated schema, deployOk evaluates the new code, and dataSafety classifies the change as safe, risky, or uncertain.
• releaseSafetyMode decides how much of that authority is automatic. MANUAL parks everything, including rollbacks. STRICT applies only deterministically additive changes automatically. NORMAL, the default, adds changes the AI judged safe. UNRESTRICTED applies everything automatically, still snapshotting managed databases first. Deploy calls accept an optional releaseSafetyMode where the strictest value wins, so a request can narrow authority for one deploy but never widen it.
• A parked release is not a failure. deployReadiness.action: CONFIRM_RELEASE means evidence is waiting for a human decision. Your job is to read it, summarize it faithfully, and confirm only after the user agrees.
• External databases that Tokay does not host get no rehearsal and no snapshot, and park under every mode except UNRESTRICTED.

What to call

Read a parked release

When deployReadiness.action is CONFIRM_RELEASE, read deployReadiness.targetDeployment. Do not assume the newest deployment row is the parked one.

query ReleaseConfirmation($serviceId: ID!) {
  service(id: $serviceId) {
    deployReadiness {
      state reason action message
      targetDeployment {
        id deployState deployWaitReason releaseSafetyMode releaseStrategy
        releaseExecutions(orderBy: ACTION_INDEX_ASC) {
          nodes {
            id actionName command releaseExecutionPhase releaseExecutionState
            impactAssessment releaseAnalysis
            projectResource { id resourceType runtimeName }
          }
        }
      }
    }
  }
}

impactAssessment and releaseAnalysis are JSON with camelCase keys. Each database's final REHEARSAL row carries impactAssessment.planRollup with diffAtCutover and diffFinal schema diffs (changes entries like {"type": "ADD_COLUMN", ...}) and the policy object. policy.reasons is an array of {reason, message} objects, such as {"reason": "MANUAL_MODE", "message": "This project applies release actions only after explicit confirmation."}. Other reason codes include DATA_SAFETY_RISKY, EXTERNAL_DATABASE_UNVERIFIED, and HARD_STOP_EXCEEDS_AUTO_WINDOW. Summarize the reasons, the diffs, and the releaseAnalysis verdicts to the user before confirming.

Confirm

mutation Confirm($deployment: ID!) {
  confirmDeploymentRelease(input: { deployment: $deployment }) {
    deployment { id deployState }
  }
}

Confirming runs the rehearsed plan against production. Tokay snapshots each managed database immediately before mutating it. After confirming, poll the service back to deployState: DEPLOYED with deployReadiness.state: UP_TO_DATE. A release that applied automatically shows the same evidence trail afterward, a REHEARSAL row and then a PRODUCTION row per action, so you can always answer what ran and why it was allowed.

The safety dial

releaseSafetyMode lives on the project (project.releaseSafetyMode) and services inherit it. A service can override with its own value, where null means inherit. Direct API clients keep the generated update contract, for example updateProject(input: { id: $id, patch: { releaseSafetyMode: MANUAL } }). Tokay MCP blocks that protected field in its generic mutation tool and uses set_release_safety, which previews the exact authority change before consuming a one time review receipt. Under NORMAL, do not expect every statement that looks destructive to park. The rehearsal runs against real data, and a drop that loses nothing observable can be judged safe and apply on its own. Change the dial only when the user asks for it. If the user wants a guaranteed gate, set MANUAL and treat CONFIRM_RELEASE as the routine path. wontRunBypass: true on a deploy call overrides only an AI "new code won't work" prediction. Rehearsal failures always block.

Migration command overrides

UNCONFIRMED_RELEASE_ACTION as a deploy blocker means Tokay found migration machinery it cannot run automatically and proposed a command. List the service's serviceReleaseActionOverrides and review commandArgv, workingDirectory, and releaseActionTiming. Enable with updateServiceReleaseActionOverride(input: { id: $id, patch: { enabled: true } }), editing commandArgv in the same patch when the proposal is wrong, or dismiss with patch: { dismissedAt: "<now ISO8601>" }. Never enable a command you have not shown the user.

Maintenance holds

deployReadiness.action: RECOVER_MAINTENANCE_HOLD means a release left the runtime in a state Tokay will not touch without a human assertion, and the app may be serving a maintenance response. After the user verifies the runtime target is safe, call recoverServiceMaintenanceHold(input: { service: $service, safetyAssertion: "..." }) with a sentence recording what was verified, then poll readiness.

Error shapes