Deploy a Pipe Sandbox Version

⚠️

BETA - This API is currently in beta testing. If you encounter issues or have feedback, contact our support team.

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: Your token must have Admin (manage) permission on the production pipe. Administering the sandbox clone is not enough.
3. Version ID: The ID of the sandbox version to deploy. You get it from Open a Pipe Sandbox Version as repoVersion.id.
4. A snapshot on both sides: both the production pipe and the sandbox clone need an uploaded snapshot, since the deploy compares the two checkpoints to work out what changed. See Create a pipe snapshot.

Step 1: Deploy the Sandbox

A deploy takes the structure you edited on the sandbox clone and applies it to the production pipe: phases, fields, automations and the rest of the versioned structure.

You pass only the version. The version already identifies both pipes, so the two checkpoints are resolved from it rather than supplied by you: the latest uploaded snapshot of each side.

mutation {
  deployRepoVersion(input: {
    repoVersionId: 77
  }) {
    operation {
      id
      kind
      status
      error
      createdAt
    }
  }
}

Input Explanation:

• repoVersionId (required): The ID of the sandbox version to deploy.

Sample Response:

The deploy is asynchronous, so the mutation records the operation and returns immediately:

{
  "data": {
    "deployRepoVersion": {
      "operation": {
        "id": "912",
        "kind": "DEPLOY",
        "status": "PENDING",
        "error": null,
        "createdAt": "2026-06-25T14:12:44Z"
      }
    }
  }
}

Step 2: Follow the Operation Until It Finishes

The returned operation is the record of the deploy, and its status is where progress lives. Read it back from the production pipe's operations list:

query {
  pipe(id: 123) {
    operations(kind: [DEPLOY]) {
      id
      status
      error
      createdAt
      updatedAt
    }
  }
}

status tells you where the deploy is:

• PENDING: recorded, the work has not started.
• RUNNING: applying the sandbox structure to the production pipe.
• SUCCEEDED: the production pipe now carries the sandbox's structure.
• FAILED: the deploy did not complete, and error explains why.

See Read a Pipe's Snapshots and Operations for the full field reference.

Response Fields

• operation.id: The deploy operation's ID.
• operation.kind: Always DEPLOY for this mutation.
• operation.status: State of the deploy. It is PENDING in the mutation's own response, since the work is queued rather than done.
• operation.error: Why the deploy failed. null unless status is FAILED. Reading it requires Admin (manage) permission on the pipe.
• operation.sourceSnapshot: Always null for a deploy. The field resolves within the operation's target pipe, and a deploy's source snapshot belongs to the sandbox clone instead.

Key Notes

• The production pipe is the authorization target: permission is checked on the pipe being changed, not on the sandbox. A token that administers only the clone receives a PERMISSION_DENIED error.
• One structural operation per pipe at a time: if a restore or another deploy is already in flight for either the production pipe or its sandbox, the request is refused with a DEPLOY_IN_PROGRESS error. Check operations(status: [PENDING, RUNNING]) first, or retry once the in-flight operation finishes.
• A version deploys once: a version that has already been deployed is refused with a REPO_VERSION_ALREADY_PUBLISHED error. Open a fresh sandbox instead.
• Both sides need a checkpoint: if either the production pipe or the sandbox clone has no uploaded snapshot, the request is refused with an INVALID_INPUT error naming repoVersionId. The same error covers a version whose sandbox pipe no longer exists.
• Snapshots are blocked while a deploy is in flight: createRepoSnapshot on the pipe is refused for as long as the deploy is PENDING or RUNNING, since the structure is being rewritten underneath it.
• What the deploy applies is fixed when the mutation is accepted: the two checkpoints are resolved once, at that moment. A snapshot uploaded afterwards does not change what the deploy applies.
• Version not found: an invalid or non-existent repoVersionId returns a RECORD_NOT_FOUND error.
• Gradual rollout: this operation is being rolled out behind the same feature flag as the sandbox itself and may not yet be available for every organization. When the flag is off, the mutation is absent from the schema and the request fails with an error naming deployRepoVersion.