Dokumentation

Scheduled deployments

Schedule a one-off agent deployment or removal.

Scheduled deployments reuse deployment jobs, approval gates, and the normal deployment workflow. In the deployment preview or removal dialog, choose Schedule for later and select a local date and time. The deployment confirmation links to Deployments → Upcoming, where you can review, reschedule, or cancel accessible scheduled jobs. Cancelled and expired schedules appear separately in History because they are jobs rather than completed deployment records. Rescheduling resets required approvals.

Create a schedule

Send a UTC ISO scheduledAt to POST /agents/deployments/dispatch. It applies to every environment in a structured deployments request. The legacy single-environment shape also accepts it. The response includes jobId, status: "scheduled", and scheduledAt, both at the top level for the first successful environment and in each successful jobs entry.

{
  "orgSlug": "your-org",
  "deployments": [{
    "environmentId": "your-environment-id",
    "environmentName": "production",
    "agentStableKeys": ["your-agent-key"]
  }],
  "scheduledAt": "2026-12-01T10:00:00.000Z"
}

Choose a time at least five minutes and at most 90 days after the request. The example timestamp must be replaced with a time in that range. Only deploy and remove can be scheduled; verify returns 400. For removal, use POST /agents/removals/dispatch with scheduledAt, or set action: "remove" on a scheduled deployment dispatch. Existing immediate endpoints keep their behavior.

The job has no compiled batches until it fires. Access and governance are checked when scheduling and again before execution. The scheduler remains the actor even though a background system session performs the work.

Approvals

The scheduling form shows the approval deadline for environments with an enabled gate. Required approvers are notified when the schedule is created. Approving records the vote and does not start the job early. Any denial stops it. Missing approvals at execution time expire the schedule. Rescheduling replaces the approval rows with new pending votes and notifies approvers again.

If the environment's gate changes, both the originally requested approvers and the current required approvers must have approved. Missing votes expire the schedule; disabling a gate does not erase votes already requested. This prevents a gate change from silently bypassing approval.

List, reschedule, and cancel

  • GET /deployments/scheduled?organizationId=... lists accessible scheduled jobs, soonest first. Add environmentId to filter. Results include scheduler name and an approval summary. Add state=history to list accessible cancelled and expired schedules.
  • PATCH /deployments/scheduled/{jobId} accepts organizationId and a new scheduledAt using the same time limits.
  • DELETE /deployments/scheduled/{jobId}?organizationId=... cancels a job before it starts.

The scheduler or an organization owner/admin may reschedule or cancel, and must still have access to the environment. A job in another organization returns 404; insufficient permission returns 403; a job that already started, was cancelled, or expired returns 409. Refresh before retrying a conflict.

Cancellation first persists cancelled; stopping the workflow run is best effort. A surviving run rereads the job and skips it. Moving a schedule earlier starts a new run; duplicate runs compete for a single database claim.

Scheduling events (scheduled, started, expired, and cancelled) are available in notification preferences and custom subscriptions.

Recovery and operation

The scheduled workflow sleeps until the requested time and rereads the job after waking. A sweep cron runs every five minutes and recovers scheduled jobs more than two minutes overdue. Trigger failure leaves the job scheduled for recovery.

Jobs more than 60 minutes overdue expire instead of running late. Set SCHEDULED_DEPLOYMENT_MAX_LATENESS_MINUTES to a positive number to change this limit; invalid values log a warning and use 60. Configure CRON_SECRET consistently for the workflow and cron routes. A sweep recovery can run later than the normal sleep path.

Apply the scheduling and notification enum migrations before deploying the application. The scheduler reference is text because the project's user IDs are strings. Job writes and scheduling RPCs remain service-role-only. Authenticated direct updates of scheduled approval rows are blocked, including for organization administrators; decisions go through the atomic API/RPC path. Immediate approval updates retain their existing permissions. Apply 20261109101500_restrict_scheduled_approval_updates.sql along with the scheduling and notification migrations.

A database claim prevents competing runs from dispatching twice. It does not provide a distributed transaction with the workflow service. A process interruption after the claim or an ambiguous workflow-start response requires investigation; the sweep handles scheduled jobs, not already claimed pending jobs. Do not blindly replay a claimed job.

The pinned workflow@4.8.5 exposes sleep(Date) and getRun().cancel(). A local smoke test created a seven-day durable wait and cancelled its run through the actual SDK. Its bundled documentation describes deployment-pinned runs. Long-wait retention and resumption across redeploys still require validation in the target Vercel project; local tests do not prove these platform properties.