Gitpod API Reference | Prebuilds

Prebuilds

prebuilds

Methods

Cancel Prebuild -> { prebuild }

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

Create Prebuild -> { prebuild }

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

Response fields

prebuild:

Prebuild

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

Request example

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

200Example

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

Create Prebuild Logs Token -> { accessToken }

post/gitpod.v1.PrebuildService/CreatePrebuildLogsToken

Creates a logs access token for a prebuild.

Use this method to:

Stream logs from a running prebuild
Access archived logs from completed prebuilds

Generated tokens are valid for one hour.

Examples

Create prebuild logs token:

Generates a token for accessing prebuild logs.
```
prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048"
```

Create Warm Pool -> { warmPool }

post/gitpod.v1.PrebuildService/CreateWarmPool

Creates a warm pool for a project and environment class.

A warm pool maintains pre-created environment instances from a prebuild snapshot so that new environments can start near-instantly.

Only one warm pool is allowed per <project, environment_class> pair. The environment class must have prebuilds enabled on the project.

The pool's snapshot is managed automatically: when a new prebuild completes for the same project and environment class, the pool's snapshot is updated and the runner rotates instances.

Examples

Create warm pool:

Creates a warm pool with 2 instances for a project and environment class.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
desiredSize: 2

Delete Prebuild -> unknown

post/gitpod.v1.PrebuildService/DeletePrebuild

Deletes a prebuild.

Prebuilds are automatically deleted after some time. Use this method to manually delete a prebuild before automatic cleanup, for example to remove a prebuild that should no longer be used.

Deletion is processed asynchronously. The prebuild will be marked for deletion and removed from the system in the background.

Examples

Delete prebuild:

Marks a prebuild for deletion and removes it from the system.
```
prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048"
```

Delete Warm Pool -> unknown

post/gitpod.v1.PrebuildService/DeleteWarmPool

Deletes a warm pool.

Deletion is processed asynchronously. The pool is marked for deletion and the runner drains instances in the background.

Warm pools are also automatically deleted when prebuilds are disabled on the project or the environment class is removed from the prebuild configuration.

Examples

Delete warm pool:

warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab"

List Prebuilds -> PrebuildsPage<

Prebuild

post/gitpod.v1.PrebuildService/ListPrebuilds

ListPrebuilds

List Warm Pools -> WarmPoolsPage<

WarmPool

post/gitpod.v1.PrebuildService/ListWarmPools

Lists warm pools with optional filtering.

Use this method to:

View all warm pools for a project
Monitor warm pool status across environment classes

Examples

List warm pools for a project:

filter:
  projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"]

Get Prebuild -> { prebuild }

post/gitpod.v1.PrebuildService/GetPrebuild

Gets details about a specific prebuild.

Use this method to:

Check prebuild status and progress
Access prebuild logs for debugging

Examples

Get prebuild details:

Retrieves comprehensive information about a prebuild.
```
prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048"
```

Get Warm Pool -> { warmPool }

post/gitpod.v1.PrebuildService/GetWarmPool

Gets details about a specific warm pool.

Use this method to:

Check warm pool status and phase
View the current snapshot being warmed
Monitor pool health

Examples

Get warm pool:

warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab"

Update Warm Pool -> { warmPool }

post/gitpod.v1.PrebuildService/UpdateWarmPool

Updates a warm pool's configuration.

Use this method to change the desired pool size.

Examples

Update pool size:

warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab"
desiredSize: 5

Domain types

Prebuild = { metadata, spec, status, 1 more... }

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

PrebuildCancelResponse = { prebuild }

PrebuildCreateLogsTokenResponse = { accessToken }

PrebuildCreateResponse = { prebuild }

PrebuildCreateWarmPoolResponse = { warmPool }

PrebuildDeleteResponse = unknown

PrebuildDeleteWarmPoolResponse = unknown

PrebuildMetadata = { createdAt, creator, updatedAt, 5 more... }

PrebuildMetadata contains metadata about the prebuild

PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED" | "PREBUILD_PHASE_PENDING" | "PREBUILD_PHASE_STARTING" | 9 more...

PrebuildPhase represents the lifecycle phase of a prebuild

PrebuildRetrieveResponse = { prebuild }

PrebuildRetrieveWarmPoolResponse = { warmPool }

PrebuildSpec = { desiredPhase, specVersion, timeout }

PrebuildSpec contains the configuration used to create a prebuild

PrebuildStatus = { phase, completionTime, environmentId, 6 more... }

PrebuildStatus contains the current status and progress of a prebuild

PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED" | "PREBUILD_TRIGGER_MANUAL" | "PREBUILD_TRIGGER_SCHEDULED"

PrebuildTrigger indicates how the prebuild was triggered

PrebuildUpdateWarmPoolResponse = { warmPool }

WarmPool = { metadata, spec, status, 1 more... }

WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per <project, environment_class> pair.

WarmPoolMetadata = { createdAt, updatedAt, environmentClassId, 3 more... }

WarmPoolMetadata contains metadata about the warm pool

WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED" | "WARM_POOL_PHASE_PENDING" | "WARM_POOL_PHASE_READY" | 3 more...

WarmPoolPhase represents the lifecycle phase of a warm pool

WarmPoolSpec = { desiredPhase, desiredSize, maxSize, 3 more... }

WarmPoolSpec contains the desired configuration for a warm pool

WarmPoolStatus = { phase, desiredSize, failureMessage, 3 more... }

WarmPoolStatus contains the current status of a warm pool as reported by the runner