# Prebuilds ## CancelPrebuild `prebuilds.cancel(PrebuildCancelParams**kwargs) -> PrebuildCancelResponse` **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" ``` ### Parameters - `prebuild_id: str` prebuild_id specifies the prebuild to cancel ### Returns - `class PrebuildCancelResponse: …` - `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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.prebuilds.cancel( prebuild_id="07e03a28-65a5-4d98-b532-8ea67b188048", ) print(response.prebuild) ``` #### 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 `prebuilds.create(PrebuildCreateParams**kwargs) -> PrebuildCreateResponse` **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 ``` ### Parameters - `project_id: str` project_id specifies the project to create a prebuild for - `spec: PrebuildSpecParam` spec contains the configuration for creating the prebuild - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. - `environment_class_id: Optional[str]` environment_class_id specifies which environment class to use for the prebuild. If not specified, uses the project's default environment class. ### Returns - `class PrebuildCreateResponse: …` - `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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) prebuild = client.prebuilds.create( project_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047", spec={ "timeout": "3600s" }, ) print(prebuild.prebuild) ``` #### 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 `prebuilds.create_logs_token(PrebuildCreateLogsTokenParams**kwargs) -> PrebuildCreateLogsTokenResponse` **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" ``` ### Parameters - `prebuild_id: str` prebuild_id specifies the prebuild for which the logs token should be created. +required ### Returns - `class PrebuildCreateLogsTokenResponse: …` - `access_token: str` access_token is the token that can be used to access the logs of the prebuild ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.prebuilds.create_logs_token( prebuild_id="07e03a28-65a5-4d98-b532-8ea67b188048", ) print(response.access_token) ``` #### Response ```json { "accessToken": "accessToken" } ``` ## CreateWarmPool `prebuilds.create_warm_pool(PrebuildCreateWarmPoolParams**kwargs) -> PrebuildCreateWarmPoolResponse` **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 ``` ### Parameters - `environment_class_id: str` environment_class_id specifies which environment class to warm. Must be listed in the project's prebuild configuration environment_class_ids. - `project_id: str` project_id specifies the project this warm pool belongs to. The project must have prebuilds enabled. - `desired_size: Optional[int]` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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 - `class PrebuildCreateWarmPoolResponse: …` - `warm_pool: 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.prebuilds.create_warm_pool( environment_class_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", project_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047", desired_size=2, ) print(response.warm_pool) ``` #### 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 `prebuilds.delete(PrebuildDeleteParams**kwargs) -> object` **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" ``` ### Parameters - `prebuild_id: str` prebuild_id specifies the prebuild to delete ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) prebuild = client.prebuilds.delete( prebuild_id="07e03a28-65a5-4d98-b532-8ea67b188048", ) print(prebuild) ``` #### Response ```json {} ``` ## DeleteWarmPool `prebuilds.delete_warm_pool(PrebuildDeleteWarmPoolParams**kwargs) -> object` **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" ``` ### Parameters - `warm_pool_id: str` warm_pool_id specifies the warm pool to delete ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.prebuilds.delete_warm_pool( warm_pool_id="a1b2c3d4-5678-9abc-def0-1234567890ab", ) print(response) ``` #### Response ```json {} ``` ## ListPrebuilds `prebuilds.list(PrebuildListParams**kwargs) -> SyncPrebuildsPage[Prebuild]` **post** `/gitpod.v1.PrebuildService/ListPrebuilds` ListPrebuilds ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` filter contains the filter options for listing prebuilds - `creator_ids: Optional[Sequence[str]]` creator_ids filters prebuilds by who created them - `executor_ids: Optional[Sequence[str]]` executor_ids filters prebuilds by whose credentials were used to run them - `phases: Optional[List[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"` - `project_ids: Optional[Sequence[str]]` project_ids filters prebuilds to specific projects - `triggered_by: Optional[List[PrebuildTrigger]]` triggered_by filters prebuilds by how they were triggered - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` - `pagination: Optional[Pagination]` pagination contains the pagination options for listing prebuilds - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class 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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.prebuilds.list() page = page.prebuilds[0] print(page.id) ``` #### 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 `prebuilds.list_warm_pools(PrebuildListWarmPoolsParams**kwargs) -> SyncWarmPoolsPage[WarmPool]` **post** `/gitpod.v1.PrebuildService/ListWarmPools` Lists warm pools with optional filtering. Use this method to: - View all warm pools for a project - Monitor warm pool status across environment classes ### Examples - List warm pools for a project: ```yaml filter: projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` filter contains the filter options for listing warm pools - `environment_class_ids: Optional[Sequence[str]]` environment_class_ids filters warm pools to specific environment classes - `project_ids: Optional[Sequence[str]]` project_ids filters warm pools to specific projects - `pagination: Optional[Pagination]` pagination contains the pagination options for listing warm pools - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.prebuilds.list_warm_pools( filter={ "project_ids": ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] }, ) page = page.warm_pools[0] print(page.id) ``` #### 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 `prebuilds.retrieve(PrebuildRetrieveParams**kwargs) -> PrebuildRetrieveResponse` **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" ``` ### Parameters - `prebuild_id: str` prebuild_id specifies the prebuild to retrieve ### Returns - `class PrebuildRetrieveResponse: …` - `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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) prebuild = client.prebuilds.retrieve( prebuild_id="07e03a28-65a5-4d98-b532-8ea67b188048", ) print(prebuild.prebuild) ``` #### 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 `prebuilds.retrieve_warm_pool(PrebuildRetrieveWarmPoolParams**kwargs) -> PrebuildRetrieveWarmPoolResponse` **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" ``` ### Parameters - `warm_pool_id: str` warm_pool_id specifies the warm pool to retrieve ### Returns - `class PrebuildRetrieveWarmPoolResponse: …` - `warm_pool: 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.prebuilds.retrieve_warm_pool( warm_pool_id="a1b2c3d4-5678-9abc-def0-1234567890ab", ) print(response.warm_pool) ``` #### 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 `prebuilds.update_warm_pool(PrebuildUpdateWarmPoolParams**kwargs) -> PrebuildUpdateWarmPoolResponse` **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 ``` ### Parameters - `warm_pool_id: str` warm_pool_id specifies the warm pool to update - `desired_size: Optional[int]` desired_size updates the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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 - `class PrebuildUpdateWarmPoolResponse: …` - `warm_pool: 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.prebuilds.update_warm_pool( warm_pool_id="a1b2c3d4-5678-9abc-def0-1234567890ab", desired_size=5, ) print(response.warm_pool) ``` #### 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 - `class 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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Prebuild Metadata - `class PrebuildMetadata: …` PrebuildMetadata contains metadata about the prebuild - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: Optional[PrebuildTrigger]` trigger describes the trigger that created this prebuild. - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` ### Prebuild Phase - `Literal["PREBUILD_PHASE_UNSPECIFIED", "PREBUILD_PHASE_PENDING", "PREBUILD_PHASE_STARTING", 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 - `class PrebuildSpec: …` PrebuildSpec contains the configuration used to create a prebuild - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `class PrebuildStatus: …` 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"` - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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 - `Literal["PREBUILD_TRIGGER_UNSPECIFIED", "PREBUILD_TRIGGER_MANUAL", "PREBUILD_TRIGGER_SCHEDULED"]` PrebuildTrigger indicates how the prebuild was triggered - `"PREBUILD_TRIGGER_UNSPECIFIED"` - `"PREBUILD_TRIGGER_MANUAL"` - `"PREBUILD_TRIGGER_SCHEDULED"` ### Warm Pool - `class 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool ### Warm Pool Metadata - `class WarmPoolMetadata: …` WarmPoolMetadata contains metadata about the warm pool - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` runner_id is the runner that manages this warm pool. Derived from the environment class. ### Warm Pool Phase - `Literal["WARM_POOL_PHASE_UNSPECIFIED", "WARM_POOL_PHASE_PENDING", "WARM_POOL_PHASE_READY", 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 - `class WarmPoolSpec: …` WarmPoolSpec contains the desired configuration for a warm pool - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. ### Warm Pool Status - `class WarmPoolStatus: …` 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"` - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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 - `class PrebuildCancelResponse: …` - `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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Prebuild Create Response - `class PrebuildCreateResponse: …` - `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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Prebuild Create Logs Token Response - `class PrebuildCreateLogsTokenResponse: …` - `access_token: str` access_token is the token that can be used to access the logs of the prebuild ### Prebuild Create Warm Pool Response - `class PrebuildCreateWarmPoolResponse: …` - `warm_pool: 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool ### Prebuild Retrieve Response - `class PrebuildRetrieveResponse: …` - `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 - `created_at: datetime` 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[str]` 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"` - `updated_at: datetime` updated_at is when the prebuild was last updated - `environment_class_id: Optional[str]` 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. - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the prebuild - `project_id: Optional[str]` project_id is the ID of the project this prebuild was created for - `triggered_by: 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 - `desired_phase: 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"` - `spec_version: Optional[str]` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `timeout: Optional[str]` 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 - `completion_time: Optional[datetime]` completion_time is when the prebuild completed (successfully or with failure) - `environment_id: Optional[str]` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `failure_message: Optional[str]` failure_message contains details about why the prebuild failed - `log_url: Optional[str]` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `snapshot_completion_percentage: Optional[int]` 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. - `snapshot_size_bytes: Optional[str]` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `warning_message: Optional[str]` 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[str]` id is the unique identifier for the prebuild ### Prebuild Retrieve Warm Pool Response - `class PrebuildRetrieveWarmPoolResponse: …` - `warm_pool: 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool ### Prebuild Update Warm Pool Response - `class PrebuildUpdateWarmPoolResponse: …` - `warm_pool: 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 - `created_at: datetime` created_at is when the warm pool was created - `updated_at: datetime` updated_at is when the warm pool was last updated - `environment_class_id: Optional[str]` environment_class_id is the environment class whose instances are warmed - `organization_id: Optional[str]` organization_id is the ID of the organization that owns the warm pool - `project_id: Optional[str]` project_id is the ID of the project this warm pool belongs to - `runner_id: Optional[str]` 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 - `desired_phase: 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"` - `desired_size: Optional[int]` 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. - `max_size: Optional[int]` 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. - `min_size: Optional[int]` 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. - `snapshot_id: Optional[str]` 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. - `spec_version: Optional[str]` 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 - `desired_size: Optional[int]` 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. - `failure_message: Optional[str]` failure_message contains details about why the warm pool is degraded or failed - `running_instances: Optional[int]` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `status_version: Optional[str]` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `stopped_instances: Optional[int]` 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[str]` id is the unique identifier for the warm pool