# Prebuilds ## CancelPrebuild **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. ```yaml prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `prebuildId: string` prebuild_id specifies the prebuild to cancel ### Returns - `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: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/CancelPrebuild \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "prebuildId": "07e03a28-65a5-4d98-b532-8ea67b188048" }' ``` #### Response ```json { "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" } } ``` ## 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. ```yaml 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. ```yaml projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" spec: timeout: "3600s" # 1 hour ``` ### Body Parameters - `projectId: string` project_id specifies the project to create a prebuild for - `spec: PrebuildSpec` 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. - `"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. - `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. ### Returns - `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: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Example ```http 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" } }' ``` #### Response ```json { "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" } } ``` ## CreatePrebuildLogsToken **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. ```yaml prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `prebuildId: string` prebuild_id specifies the prebuild for which the logs token should be created. +required ### Returns - `accessToken: string` access_token is the token that can be used to access the logs of the prebuild ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/CreatePrebuildLogsToken \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "prebuildId": "07e03a28-65a5-4d98-b532-8ea67b188048" }' ``` #### Response ```json { "accessToken": "accessToken" } ``` ## CreateWarmPool **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 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. ```yaml projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" desiredSize: 2 ``` ### Body Parameters - `environmentClassId: string` environment_class_id specifies which environment class to warm. Must be listed in the project's prebuild configuration environment_class_ids. - `projectId: string` project_id specifies the project this warm pool belongs to. The project must have prebuilds enabled. - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. ### Returns - `warmPool: WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/CreateWarmPool \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "environmentClassId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "projectId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047" }' ``` #### Response ```json { "warmPool": { "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "updatedAt": "2019-12-27T18:11:19.117Z", "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "runnerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 1, "maxSize": 1, "minSize": 20, "snapshotId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "specVersion": "specVersion" }, "status": { "phase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 0, "failureMessage": "failureMessage", "runningInstances": 0, "statusVersion": "statusVersion", "stoppedInstances": 0 }, "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } ``` ## DeletePrebuild **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. ```yaml prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `prebuildId: string` prebuild_id specifies the prebuild to delete ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/DeletePrebuild \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "prebuildId": "07e03a28-65a5-4d98-b532-8ea67b188048" }' ``` #### Response ```json {} ``` ## DeleteWarmPool **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: ```yaml warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab" ``` ### Body Parameters - `warmPoolId: string` warm_pool_id specifies the warm pool to delete ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/DeleteWarmPool \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "warmPoolId": "a1b2c3d4-5678-9abc-def0-1234567890ab" }' ``` #### Response ```json {} ``` ## ListPrebuilds **post** `/gitpod.v1.PrebuildService/ListPrebuilds` ListPrebuilds ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { creatorIds, executorIds, phases, 2 more }` filter contains the filter options for listing prebuilds - `creatorIds: optional array of string` creator_ids filters prebuilds by who created them - `executorIds: optional array of string` executor_ids filters prebuilds by whose credentials were used to run them - `phases: optional array of PrebuildPhase` phases filters prebuilds by their current phase - `"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"` - `projectIds: optional array of string` project_ids filters prebuilds to specific projects - `triggeredBy: optional array of PrebuildTrigger` triggered_by filters prebuilds by how they were triggered - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing prebuilds - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `pagination: optional object { nextToken }` pagination contains the pagination response - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results - `prebuilds: optional array of Prebuild` prebuilds are the prebuilds that matched the query - `metadata: PrebuildMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/ListPrebuilds \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "prebuilds": [ { "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" } ] } ``` ## ListWarmPools **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: ```yaml filter: projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { environmentClassIds, projectIds }` filter contains the filter options for listing warm pools - `environmentClassIds: optional array of string` environment_class_ids filters warm pools to specific environment classes - `projectIds: optional array of string` project_ids filters warm pools to specific projects - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing warm pools - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `pagination: optional object { nextToken }` pagination contains the pagination response - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results - `warmPools: optional array of WarmPool` warm_pools are the warm pools that matched the query - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/ListWarmPools \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "warmPools": [ { "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "updatedAt": "2019-12-27T18:11:19.117Z", "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "runnerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 1, "maxSize": 1, "minSize": 20, "snapshotId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "specVersion": "specVersion" }, "status": { "phase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 0, "failureMessage": "failureMessage", "runningInstances": 0, "statusVersion": "statusVersion", "stoppedInstances": 0 }, "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } ] } ``` ## GetPrebuild **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. ```yaml prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `prebuildId: string` prebuild_id specifies the prebuild to retrieve ### Returns - `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: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/GetPrebuild \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "prebuildId": "07e03a28-65a5-4d98-b532-8ea67b188048" }' ``` #### Response ```json { "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" } } ``` ## GetWarmPool **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: ```yaml warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab" ``` ### Body Parameters - `warmPoolId: string` warm_pool_id specifies the warm pool to retrieve ### Returns - `warmPool: WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/GetWarmPool \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "warmPoolId": "a1b2c3d4-5678-9abc-def0-1234567890ab" }' ``` #### Response ```json { "warmPool": { "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "updatedAt": "2019-12-27T18:11:19.117Z", "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "runnerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 1, "maxSize": 1, "minSize": 20, "snapshotId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "specVersion": "specVersion" }, "status": { "phase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 0, "failureMessage": "failureMessage", "runningInstances": 0, "statusVersion": "statusVersion", "stoppedInstances": 0 }, "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } ``` ## UpdateWarmPool **post** `/gitpod.v1.PrebuildService/UpdateWarmPool` Updates a warm pool's configuration. Use this method to change the desired pool size. ### Examples - Update pool size: ```yaml warmPoolId: "a1b2c3d4-5678-9abc-def0-1234567890ab" desiredSize: 5 ``` ### Body Parameters - `warmPoolId: string` warm_pool_id specifies the warm pool to update - `desiredSize: optional number` desired_size updates the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. - `maxSize: optional number` max_size updates the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size updates the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. ### Returns - `warmPool: WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.PrebuildService/UpdateWarmPool \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "warmPoolId": "a1b2c3d4-5678-9abc-def0-1234567890ab" }' ``` #### Response ```json { "warmPool": { "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "updatedAt": "2019-12-27T18:11:19.117Z", "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "runnerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 1, "maxSize": 1, "minSize": 20, "snapshotId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "specVersion": "specVersion" }, "status": { "phase": "WARM_POOL_PHASE_UNSPECIFIED", "desiredSize": 0, "failureMessage": "failureMessage", "runningInstances": 0, "statusVersion": "statusVersion", "stoppedInstances": 0 }, "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } ``` ## Domain Types ### Prebuild - `Prebuild object { metadata, spec, status, id }` 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: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Prebuild Metadata - `PrebuildMetadata object { createdAt, creator, updatedAt, 5 more }` PrebuildMetadata contains metadata about the prebuild - `createdAt: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` ### Prebuild Phase - `PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED" or "PREBUILD_PHASE_PENDING" or "PREBUILD_PHASE_STARTING" or 9 more` PrebuildPhase represents the lifecycle phase of a prebuild - `"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"` ### Prebuild Spec - `PrebuildSpec object { desiredPhase, specVersion, timeout }` PrebuildSpec contains the configuration used to create a 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. - `"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. ### Prebuild Status - `PrebuildStatus object { phase, completionTime, environmentId, 6 more }` PrebuildStatus contains the current status and progress of a prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `"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) - `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. - `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. - `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. - `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. ### Prebuild Trigger - `PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED" or "PREBUILD_TRIGGER_MANUAL" or "PREBUILD_TRIGGER_SCHEDULED"` PrebuildTrigger indicates how the prebuild was triggered - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` ### Warm Pool - `WarmPool object { metadata, spec, status, id }` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool ### Warm Pool Metadata - `WarmPoolMetadata object { createdAt, updatedAt, environmentClassId, 3 more }` WarmPoolMetadata contains metadata about the warm pool - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. ### Warm Pool Phase - `WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED" or "WARM_POOL_PHASE_PENDING" or "WARM_POOL_PHASE_READY" or 3 more` WarmPoolPhase represents the lifecycle phase of a warm pool - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` ### Warm Pool Spec - `WarmPoolSpec object { desiredPhase, desiredSize, maxSize, 3 more }` WarmPoolSpec contains the desired configuration for a warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. ### Warm Pool Status - `WarmPoolStatus object { phase, desiredSize, failureMessage, 3 more }` WarmPoolStatus contains the current status of a warm pool as reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. ### Prebuild Cancel Response - `PrebuildCancelResponse object { prebuild }` - `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: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Prebuild Create Response - `PrebuildCreateResponse object { prebuild }` - `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: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Prebuild Create Logs Token Response - `PrebuildCreateLogsTokenResponse object { accessToken }` - `accessToken: string` access_token is the token that can be used to access the logs of the prebuild ### Prebuild Create Warm Pool Response - `PrebuildCreateWarmPoolResponse object { warmPool }` - `warmPool: WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool ### Prebuild Delete Response - `PrebuildDeleteResponse = unknown` ### Prebuild Delete Warm Pool Response - `PrebuildDeleteWarmPoolResponse = unknown` ### Prebuild Retrieve Response - `PrebuildRetrieveResponse object { prebuild }` - `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: string` created_at is when the prebuild was created - `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: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"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 - `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. - `executor: optional Subject` 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. - `organizationId: optional string` organization_id is the ID of the organization that owns the prebuild - `projectId: optional string` project_id is the ID of the project this prebuild was created for - `triggeredBy: optional PrebuildTrigger` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `spec: PrebuildSpec` 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. - `"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. - `status: PrebuildStatus` status contains the current status and progress of the prebuild - `phase: PrebuildPhase` phase is the current phase of the prebuild lifecycle - `completionTime: optional string` completion_time is when the prebuild completed (successfully or with failure) - `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. - `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. - `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. - `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 ### Prebuild Retrieve Warm Pool Response - `PrebuildRetrieveWarmPoolResponse object { warmPool }` - `warmPool: WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool ### Prebuild Update Warm Pool Response - `PrebuildUpdateWarmPoolResponse object { warmPool }` - `warmPool: WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `metadata: WarmPoolMetadata` metadata contains organizational and ownership information - `createdAt: string` created_at is when the warm pool was created - `updatedAt: string` updated_at is when the warm pool was last updated - `environmentClassId: optional string` environment_class_id is the environment class whose instances are warmed - `organizationId: optional string` organization_id is the ID of the organization that owns the warm pool - `projectId: optional string` project_id is the ID of the project this warm pool belongs to - `runnerId: optional string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `spec: WarmPoolSpec` spec contains the desired configuration for this warm pool - `desiredPhase: optional WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `"WARM_POOL_PHASE_UNSPECIFIED"` - `"WARM_POOL_PHASE_PENDING"` - `"WARM_POOL_PHASE_READY"` - `"WARM_POOL_PHASE_DEGRADED"` - `"WARM_POOL_PHASE_DELETING"` - `"WARM_POOL_PHASE_DELETED"` - `desiredSize: optional number` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `maxSize: optional number` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `minSize: optional number` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `snapshotId: optional string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `specVersion: optional string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `status: WarmPoolStatus` status contains the current status reported by the runner - `phase: WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `desiredSize: optional number` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `failureMessage: optional string` failure_message contains details about why the warm pool is degraded or failed - `runningInstances: optional number` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `statusVersion: optional string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stoppedInstances: optional number` stopped_instances is the number of pre-provisioned but stopped instances in the pool. When a running instance is claimed, stopped instances are used to backfill the running pool faster than provisioning from scratch. Stopped instances only incur storage costs, allowing a larger total pool at lower cost than keeping all instances running. - `id: optional string` id is the unique identifier for the warm pool