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

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 deploymentReleaseSession is one ordered resource plan. Its typed combinedImpactAssessment contains observed facts, releaseAnalysis contains AI verdicts, and policyResult.reasons explains any park. Internal rehearsal receipts remain flexible JSON; clients never parse them.
  • 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.
  • Only migrations Tokay runs as a release step are rehearsed and snapshotted. Those are detected migration tools and releaseActionOverrides commands, including the one Tokay proposes from the code where it detects no tool (overrideSource: AI_PROPOSED, ai:migrations), which runs from the start. Schema changes the app applies itself as it starts change production directly. That covers DDL such as CREATE TABLE IF NOT EXISTS, ORM auto-sync, and a migration tool called from the start command or startup code. Those changes get no restore point and never appear in a rollback's impact.schemaChanges. Put schema changes in a migration tool Tokay detects.

What to call

To Use
Detect a park deployReadiness { action targetDeployment { id } }
Read the evidence targetDeployment.releaseSessions
Apply the parked plan confirmDeploymentRelease
Change the dial setProjectReleaseSafety / setServiceReleaseSafety
Review or fix a proposed migration command service.releaseActionOverrides, updateServiceReleaseActionOverride
Read a project's preview project { pushMode latestPreview { state message updatePending failedService { name } } previewLinks { url service { name type } } }
Go live from a preview deployProject or deployService, only when the user asks

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 {
      status reason action message
      targetDeployment {
        id state waitReason releaseSafetyMode releaseStrategy
        releaseSessions(first: 100, orderBy: CREATED_AT_ASC) {
          nodes {
            id isExternalTarget
            projectResource { id resourceType runtimeName }
            combinedImpactAssessment {
              preTrafficChanges { type operation requiresConfirmation database subject }
              finalChanges { type operation requiresConfirmation database subject }
              tableDeltas { database tableName inserts updates deletes }
              durationMs hasUnknownImpact
              unknownReasons { code database message }
              hasUnverifiedSideEffects
            }
            releaseAnalysis {
              currentCodeSafe currentCodeSafeReasons newCodeSafe newCodeSafeReasons
              dataSafety dataSafetyReasons startupMigrationWarning
            }
            policyResult {
              decision
              reasons { code message analysisReasons observedSeconds windowSeconds }
            }
            actions(first: 100, orderBy: ACTION_INDEX_ASC) {
              nodes {
                commandDisplay evidenceState
                releaseExecutions(first: 20, orderBy: CREATED_AT_ASC) {
                  nodes { type state exitCode logTail }
                }
              }
            }
          }
        }
      }
    }
  }
}

Summarize policyResult.reasons, destructive finalChanges, and the releaseAnalysis verdicts before confirming. preTrafficChanges is what the new code first sees. finalChanges is the completed plan. dataSafety is SAFE, RISKY, or UNCERTAIN. Reason codes include DATA_SAFETY_RISKY, EXTERNAL_DATABASE_UNVERIFIED, HARD_STOP_EXCEEDS_AUTO_WINDOW, MANUAL_MODE, CONSUMERS_BEHIND (see Schema services), REAPPLIES_UNDONE_CHANGE (the release changes data again after a restore undid a release, before one of this service's own releases changed that database), TOKAY_AUTHORED_DATA_CHANGE (it rewrites rows in a migration a Tokay fix proposal wrote), LARGE_DATA_LOSS (it loses at least half of a table that held at least 1,000 rows, or at least 100,000 rows of any table, a dropped table included, whatever the analysis says), and LAST_RELEASE_STOPPED (the database's last migration was stopped and its data restored).

Confirm

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

The first call changes nothing and fails with CONFIRMATION_REQUIRED, carrying the evidence summary and a token in extensions.confirmation. Repeat it with confirmationToken added to the input once the user agrees. Confirming runs the rehearsed plan against production. Tokay snapshots each managed database immediately before mutating it. After confirming, poll the service back to state: DEPLOYED with deployReadiness.status: 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.

Going live from a preview

A project set to preview each push (deployMode = PREVIEW) deploys its pushes as auto-deploy does until one of its services other than a SCHEMA has deployed. From then on project.pushMode reads PREVIEW, and each push runs first in a preview: the new versions on a copy of the project's data, with its real values, waiting there until someone goes live. The live app is untouched until then. Choosing PREVIEW with setProjectDeployMode needs deploy authority and fails with PROJECT_PREVIEW_ENGINE_UNSUPPORTED in a project that uses Mongo or Redis.

In the preview every app, and every scheduled job's run, gets TOKAY_PREVIEW=1, absent live. Use it to hold back side effects you don't want from a trial, such as outgoing email, or to label its pages. Its values are live's, except a Config or Secret set for the preview alone with environment: PREVIEW on setProjectSecretValueByName or setProjectConfigValueByName. clearProjectSecretValueOverride or clearProjectConfigValueOverride with environment: PREVIEW makes the preview inherit live's value again. A preview is never patched: a newer push, a changed preview value, an allowlist change or an import builds it again from a fresh copy of the data.

Readiness says where the preview is:

  • PREVIEW_PREPARING with WAIT: Tokay is copying the data, running the new versions' migrations on the copy and starting them, or preparing it again for a newer push (latestPreview.updatePending). A workspace runs one project's preview at a time, so another project's waits here (latestPreview.waitReason: OTHER_PREVIEW). Poll.
  • WORKSPACE_STOPPED with START_WORKSPACE: a push never starts a stopped workspace. Ask the user, then start it, or call openProjectPreview, which starts it.
  • PREVIEW_READY or PREVIEW_CLOSED with DEPLOY: the new versions run, or ran, and wait to go live. A ready preview closes after an hour without a person's request, for lack of memory, or when the workspace stops (latestPreview.closedReason). openProjectPreview starts it again from a fresh copy. discardProjectPreview drops the waiting versions and imports instead.
  • PREVIEW_UNAVAILABLE with CONTACT_SUPPORT: Tokay couldn't prepare it. Call openProjectPreview once, which prepares it again from a fresh copy. If it reads unavailable again, show the user message and supportRef.
  • PREVIEW_VERSION_FAILED: a new version failed in the preview. latestPreview.failedService names it and message says why. Follow action when the cause is in the code or its settings. When it is CONTACT_SUPPORT, call openProjectPreview once first. A version that fails in a preview never reads RETRY.
  • PREVIEW_DISCARDED: someone discarded the waiting versions. Readiness reads UP_TO_DATE, but that code isn't live. The next push or database import previews again.

openProjectPreview and discardProjectPreview need deploy authority, and fail with PROJECT_PREVIEW_NOT_FOUND when no preview is open any more, as after it went live or ended. Read readiness again then. Repeating a discard while it holds changes nothing.

Try it. project.previewLinks { url service { name type } } holds each WEB and FUNCTION service's preview address, and MCP get_deployment_status returns it beside latestPreview. App access control for agents covers opening one under Previews. A scheduled job never runs on its own in a preview. Scheduled runs in Operating and recovering services for agents covers running one there.

What it can reach. A preview's server code reaches only the project's allowed host names (project.previewAllowedHosts), over HTTPS on 443 or HTTP on 80, and its pages reach them only over HTTPS. Any other name, the project's own live addresses included, doesn't resolve, so an outside call failing there may be the allowlist rather than the app. latestPreview.blockedRequests lists what browsers reported the preview's pages tried and were refused, never verified, and is empty unless you can deploy the project. Its allowable says whether createProjectPreviewAllowedHost(input: { project, host }) would help: ALLOWABLE, or why not (ALREADY_ALLOWED, OWN_ADDRESS, NOT_A_HOST_NAME, SCHEME_OR_PORT_NOT_ALLOWED). The allowlist holds at most 100 exact names, with no wildcards or IP addresses. Allowing a name needs deploy authority and rebuilds the preview, so ask the user first. A call to an allowed name is real: the preview runs with the project's real Secrets, and jobs queued in the copied data may run again there.

Go live only when the user asks. Going live is deployProject or deployService (MCP deploy), the same deploy as anywhere else, and it asks nothing more, since the call is the decision. It ships the versions waiting in the preview, discarded ones included, and the preview ends. setProjectDeployMode to AUTOMATIC ships what waits at once and ends the preview. MANUAL ends it and leaves what waits for a deploy.

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 call setProjectReleaseSafety(input: { project: $id, releaseSafetyMode: MANUAL }) or setServiceReleaseSafety(input: { service: $id, releaseSafetyMode: null }). Loosening the effective mode requires PROJECT_DESTROY and confirms first: the first call fails with CONFIRMATION_REQUIRED and its impact, and the repeated call with confirmationToken applies it. Tightening needs only PROJECT_WRITE and applies at once. 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. bypassRunPrediction: true on a deploy call overrides only an AI "new code won't work" prediction. Rehearsal failures always block.

A release that drops or lossily changes schema, or deletes or rewrites existing rows, has policyResult.isDestructive: true, whether it parked or applied on its own. Once it runs, Tokay tells the user: the service's Activity gets a warning naming what changed, and whoever deployed it gets an email. Its restore point's expiresAt says how long it is kept, 7 days from the release.

Schema services

When several services use one database, its migrations belong to the database, not to one of them. Tokay turns the migration source those services use into the database's schema service: a service of type SCHEMA named <database>-migrations, which never runs. Its deployment applies each migration once, before any service using the database starts new code, and its one rehearsal judges all of them. Its currentCodeSafe covers every service using the database that has code running, and each reason starts with that service's name. A push that changes only migrations deploys the schema service alone and leaves the other services as they are. A push that changes only code leaves the schema service as it is, unless it changes which migrations exist: a dependency that ships migrations, or an app added to Django's settings, a Rails engine's migration path or a Laravel provider that loads more.

  • A service waiting on its database's migration reads deployReadiness.reason: WAITING_FOR_SCHEMA_UPDATE and action: WAIT while the migration rehearses or runs, with targetService set to the schema service and targetDeployment to its deployment. When the migration parks for confirmation, the waiting service keeps that reason but reads action: CONFIRM_RELEASE with the same targets: confirm the schema service's deployment as any release. Branch on the action and targetDeployment, not on the reason. Its attention is NONE, since the schema service's own readiness carries the task.
  • A migration whose command started runs to its end. Meanwhile a deploy that would start another migration on that database, and rollbackService on a service using it, fail with SCHEMA_RELEASE_RUNNING. Wait for the migration, then retry.
  • CONSUMERS_BEHIND in policyResult.reasons means the release changes existing tables while services named in its services may run code from before the migration. A service in the same repository stops counting once it deploys a commit that holds the migration. A service in another repository can never be checked, so the change needs confirmation, except in UNRESTRICTED. Across repositories, change schemas in two steps: add the new shape, deploy every service, then remove the old one.
  • A failed migration fails the deployments that waited on it. Their rootFailureDiagnosis is the migration's.
  • SCHEMA_SOURCE_CONFLICT means two migration sources target one database. The services keep running the second source's migrations themselves, so give the database one source.

Migration command overrides

Where Tokay detects no migration tool, it proposes a command from the code: a releaseActionOverrides entry named ai:migrations with overrideSource: AI_PROPOSED, which is enabled and runs as a release step from the start, rehearsed and snapshotted like a detected tool's. Show the user the proposed command. List the service's releaseActionOverrides and review commandArgv, workingDirectory, and timing. Fix a wrong one with updateServiceReleaseActionOverride(input: { id: $id, patch: { commandArgv: [...] } }), or turn it off with patch: { isEnabled: false }. Tokay never proposes over an entry it already proposed, so your edit or the user's stays.

Maintenance holds

deployReadiness.action: ROLL_BACK means a hard-stop release changed the database and then failed, so the service serves its maintenance response. The version before the release may not run on the data as it is now. Roll back to deployReadiness.targetDeployment, which is still the current deployment, with rollbackService and restoreData: true to put the data back as it was before the release. Nothing was written to it while the service was down, though other services using the same database may have written. Or push a fix, which takes the hold over. See the operations reference for rollback.

Error shapes

You see It means Do this
deployReadiness.action: CONFIRM_RELEASE Evidence is parked for a decision Read targetDeployment, summarize, confirm only with user agreement
waitReason: AWAITING_RELEASE_CONFIRMATION Same park, seen from the deployment row Follow the readiness action, not this field alone
state: FAILED on a REHEARSAL row The migration failed against the clone Fix the migration and push again. Rehearsal failures never reach production
policyResult.reasons contains EXTERNAL_DATABASE_UNVERIFIED Tokay cannot rehearse a database it does not host Warn the user there is no rehearsal or snapshot behind this confirm
policyResult.reasons contains CONSUMERS_BEHIND Services using the database may run code without this migration Name them to the user; deploy same-repository ones forward first, or confirm
extensions.reason: SCHEMA_RELEASE_RUNNING A migration on that database is still running Wait for it to finish, then retry
A schema service's deployment fails with SCHEMA_RUNNER_REMOVED or SCHEMA_RUNNER_INELIGIBLE The service its migrations run with was deleted, or now uses a second database Push a change, or give the migrations their own folder