API Reference

Prebuilds

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

CancelPrebuild

client.Prebuilds.Cancel(ctx, body) (*PrebuildCancelResponse, error)

POST/gitpod.v1.PrebuildService/CancelPrebuild

Cancels a running prebuild.

Use this method to:

• Stop prebuilds that are no longer needed
• Free up resources for other operations

Examples

• Cancel prebuild:

  Stops a running prebuild and cleans up resources.

  prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048"

ParametersExpand Collapse

body PrebuildCancelParams

PrebuildID param.Field[string]

prebuild_id specifies the prebuild to cancel

formatuuid

ReturnsExpand Collapse

type PrebuildCancelResponse struct{…}

Prebuild Prebuild

Prebuild represents a prebuild for a project that creates a snapshot for faster environment startup times.

Metadata PrebuildMetadata

metadata contains organizational and ownership information

CreatedAt Time

created_at is when the prebuild was created

formatdate-time

Creator Subject

creator is the identity of who created the prebuild. For manual prebuilds, this is the user who triggered it. For scheduled prebuilds, this is the configured executor.

ID stringOptional

id is the UUID of the subject

formatuuid

Principal PrincipalOptional

Principal is the principal of the subject

One of the following:

const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"

const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"

const PrincipalUser Principal = "PRINCIPAL_USER"

const PrincipalRunner Principal = "PRINCIPAL_RUNNER"

const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"

const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"

const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"

UpdatedAt Time

updated_at is when the prebuild was last updated

formatdate-time

EnvironmentClassID stringOptional

environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project’s default environment class.

formatuuid

Executor SubjectOptional

executor is the identity used to run the prebuild. The executor’s SCM credentials are used to clone the repository. If not set, the creator’s identity is used.

ID stringOptional

id is the UUID of the subject

formatuuid

Principal PrincipalOptional

Principal is the principal of the subject

One of the following:

const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"

const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"

const PrincipalUser Principal = "PRINCIPAL_USER"

const PrincipalRunner Principal = "PRINCIPAL_RUNNER"

const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"

const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"

const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"

OrganizationID stringOptional

organization_id is the ID of the organization that owns the prebuild

formatuuid

ProjectID stringOptional

project_id is the ID of the project this prebuild was created for

formatuuid

TriggeredBy PrebuildTriggerOptional

trigger describes the trigger that created this prebuild.

One of the following:

const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"

const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"

const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"

Spec PrebuildSpec

spec contains the configuration used to create this prebuild

DesiredPhase PrebuildPhaseOptional

desired_phase is the desired phase of the prebuild. Used to signal cancellation or other state changes. This field is managed by the API and reconciler.

One of the following:

const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"

const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"

const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"

const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"

const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"

const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"

const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"

const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"

const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"

const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"

const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"

const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"

SpecVersion stringOptional

spec_version is incremented each time the spec is updated. Used for optimistic concurrency control.

Timeout stringOptional

timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours.

formatregex

Status PrebuildStatus

status contains the current status and progress of the prebuild

Phase PrebuildPhase

phase is the current phase of the prebuild lifecycle

One of the following:

const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"

const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"

const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"

const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"

const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"

const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"

const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"

const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"

const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"

const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"

const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"

const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"

CompletionTime TimeOptional

completion_time is when the prebuild completed (successfully or with failure)

formatdate-time

EnvironmentID stringOptional

environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created.

formatuuid

FailureMessage stringOptional

failure_message contains details about why the prebuild failed

LogURL stringOptional

log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs.

formaturi

SnapshotCompletionPercentage int64Optional

snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider.

formatint32

maximum100

SnapshotSizeBytes stringOptional

snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED).

StatusVersion stringOptional

status_version is incremented each time the status is updated. Used for optimistic concurrency control.

WarningMessage stringOptional

warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild.

ID stringOptional

id is the unique identifier for the prebuild

formatuuid

CancelPrebuild

Go

HTTP

TypeScript

Python

Go

package main

import (
  "context"
  "fmt"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  response, err := client.Prebuilds.Cancel(context.TODO(), gitpod.PrebuildCancelParams{
    PrebuildID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Prebuild)
}

200 example

{
  "prebuild": {
    "metadata": {
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "executor": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "triggeredBy": "PREBUILD_TRIGGER_UNSPECIFIED"
    },
    "spec": {
      "desiredPhase": "PREBUILD_PHASE_UNSPECIFIED",
      "specVersion": "specVersion",
      "timeout": "+9125115.360s"
    },
    "status": {
      "phase": "PREBUILD_PHASE_UNSPECIFIED",
      "completionTime": "2019-12-27T18:11:19.117Z",
      "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "failureMessage": "failureMessage",
      "logUrl": "https://example.com",
      "snapshotCompletionPercentage": 100,
      "snapshotSizeBytes": "snapshotSizeBytes",
      "statusVersion": "statusVersion",
      "warningMessage": "warningMessage"
    },
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  }
}

Returns Examples

200 example

{
  "prebuild": {
    "metadata": {
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "executor": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "triggeredBy": "PREBUILD_TRIGGER_UNSPECIFIED"
    },
    "spec": {
      "desiredPhase": "PREBUILD_PHASE_UNSPECIFIED",
      "specVersion": "specVersion",
      "timeout": "+9125115.360s"
    },
    "status": {
      "phase": "PREBUILD_PHASE_UNSPECIFIED",
      "completionTime": "2019-12-27T18:11:19.117Z",
      "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "failureMessage": "failureMessage",
      "logUrl": "https://example.com",
      "snapshotCompletionPercentage": 100,
      "snapshotSizeBytes": "snapshotSizeBytes",
      "statusVersion": "statusVersion",
      "warningMessage": "warningMessage"
    },
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  }
}