CreatePrebuild

POST/gitpod.v1.PrebuildService/CreatePrebuild

Creates a prebuild for a project.

Use this method to:

Create on-demand prebuilds for faster environment startup
Trigger prebuilds after repository changes
Generate prebuilds for specific environment classes

The prebuild process creates an environment, runs the devcontainer prebuild lifecycle, and creates a snapshot for future environment provisioning.

Examples

Create basic prebuild:

Creates a prebuild for a project using default settings.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
spec:
  timeout: "3600s"  # 60 minutes default

Create prebuild with custom environment class:

Creates a prebuild with a specific environment class and timeout.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
spec:
  timeout: "3600s"  # 1 hour

Body ParametersJSONExpand Collapse

projectId: string

project_id specifies the project to create a prebuild for

formatuuid

spec: PrebuildSpec { desiredPhase, specVersion, timeout }

spec contains the configuration for creating the prebuild

desiredPhase: optional PrebuildPhase

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:

"PREBUILD_PHASE_UNSPECIFIED"

"PREBUILD_PHASE_PENDING"

"PREBUILD_PHASE_STARTING"

"PREBUILD_PHASE_RUNNING"

"PREBUILD_PHASE_STOPPING"

"PREBUILD_PHASE_SNAPSHOTTING"

"PREBUILD_PHASE_COMPLETED"

"PREBUILD_PHASE_FAILED"

"PREBUILD_PHASE_CANCELLING"

"PREBUILD_PHASE_CANCELLED"

"PREBUILD_PHASE_DELETING"

"PREBUILD_PHASE_DELETED"

specVersion: optional string

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

timeout: optional string

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

environmentClassId: optional string

environment_class_id specifies which environment class to use for the prebuild. If not specified, uses the project’s default environment class.

formatuuid

ReturnsExpand Collapse

prebuild: Prebuild { metadata, spec, status, id }

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

metadata: PrebuildMetadata { createdAt, creator, updatedAt, 5 more }

metadata contains organizational and ownership information

createdAt: string

created_at is when the prebuild was created

formatdate-time

creator: Subject { id, principal }

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: optional string

id is the UUID of the subject

formatuuid

principal: optional Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

updatedAt: string

updated_at is when the prebuild was last updated

formatdate-time

environmentClassId: optional string

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: optional Subject { id, principal }

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: optional string

id is the UUID of the subject

formatuuid

principal: optional Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

organizationId: optional string

organization_id is the ID of the organization that owns the prebuild

formatuuid

projectId: optional string

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

formatuuid

triggeredBy: optional PrebuildTrigger

trigger describes the trigger that created this prebuild.

One of the following:

"PREBUILD_TRIGGER_UNSPECIFIED"

"PREBUILD_TRIGGER_MANUAL"

"PREBUILD_TRIGGER_SCHEDULED"

spec: PrebuildSpec { desiredPhase, specVersion, timeout }

spec contains the configuration used to create this prebuild

desiredPhase: optional PrebuildPhase

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:

"PREBUILD_PHASE_UNSPECIFIED"

"PREBUILD_PHASE_PENDING"

"PREBUILD_PHASE_STARTING"

"PREBUILD_PHASE_RUNNING"

"PREBUILD_PHASE_STOPPING"

"PREBUILD_PHASE_SNAPSHOTTING"

"PREBUILD_PHASE_COMPLETED"

"PREBUILD_PHASE_FAILED"

"PREBUILD_PHASE_CANCELLING"

"PREBUILD_PHASE_CANCELLED"

"PREBUILD_PHASE_DELETING"

"PREBUILD_PHASE_DELETED"

specVersion: optional string

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

timeout: optional string

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 { phase, completionTime, environmentId, 6 more }

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:

"PREBUILD_PHASE_UNSPECIFIED"

"PREBUILD_PHASE_PENDING"

"PREBUILD_PHASE_STARTING"

"PREBUILD_PHASE_RUNNING"

"PREBUILD_PHASE_STOPPING"

"PREBUILD_PHASE_SNAPSHOTTING"

"PREBUILD_PHASE_COMPLETED"

"PREBUILD_PHASE_FAILED"

"PREBUILD_PHASE_CANCELLING"

"PREBUILD_PHASE_CANCELLED"

"PREBUILD_PHASE_DELETING"

"PREBUILD_PHASE_DELETED"

completionTime: optional string

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

formatdate-time

environmentId: optional string

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: optional string

failure_message contains details about why the prebuild failed

logUrl: optional string

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

formaturi

snapshotCompletionPercentage: optional number

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: optional string

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

statusVersion: optional string

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

warningMessage: optional string

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: optional string

id is the unique identifier for the prebuild

formatuuid

CreatePrebuild

curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/CreatePrebuild \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "projectId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047",
          "spec": {
            "timeout": "3600s"
          }
        }'

{
  "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

{
  "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"
  }
}