# Prebuilds ## CancelPrebuild `client.Prebuilds.Cancel(ctx, body) (*PrebuildCancelResponse, error)` **post** `/gitpod.v1.PrebuildService/CancelPrebuild` Cancels a running prebuild. Use this method to: - Stop prebuilds that are no longer needed - Free up resources for other operations ### Examples - Cancel prebuild: Stops a running prebuild and cleans up resources. ```yaml prebuildId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Parameters - `body PrebuildCancelParams` - `PrebuildID param.Field[string]` prebuild_id specifies the prebuild to cancel ### Returns - `type PrebuildCancelResponse struct{…}` - `Prebuild Prebuild` Prebuild represents a prebuild for a project that creates a snapshot for faster environment startup times. - `Metadata PrebuildMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the prebuild was created - `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 string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `UpdatedAt Time` updated_at is when the prebuild was last updated - `EnvironmentClassID string` environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project's default environment class. - `Executor Subject` executor is the identity used to run the prebuild. The executor's SCM credentials are used to clone the repository. If not set, the creator's identity is used. - `OrganizationID string` organization_id is the ID of the organization that owns the prebuild - `ProjectID string` project_id is the ID of the project this prebuild was created for - `TriggeredBy PrebuildTrigger` trigger describes the trigger that created this prebuild. - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` - `Spec PrebuildSpec` spec contains the configuration used to create this prebuild - `DesiredPhase 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. - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Timeout string` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. - `Status PrebuildStatus` status contains the current status and progress of the prebuild - `Phase PrebuildPhase` phase is the current phase of the prebuild lifecycle - `CompletionTime Time` completion_time is when the prebuild completed (successfully or with failure) - `EnvironmentID string` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `FailureMessage string` failure_message contains details about why the prebuild failed - `LogURL string` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `SnapshotCompletionPercentage int64` snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider. - `SnapshotSizeBytes string` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `WarningMessage string` warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild. - `ID string` id is the unique identifier for the prebuild ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Prebuilds.Cancel(context.TODO(), gitpod.PrebuildCancelParams{ PrebuildID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.Prebuild) } ``` #### 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 `client.Prebuilds.New(ctx, body) (*PrebuildNewResponse, error)` **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 - `body PrebuildNewParams` - `ProjectID param.Field[string]` project_id specifies the project to create a prebuild for - `Spec param.Field[PrebuildSpec]` spec contains the configuration for creating the prebuild - `EnvironmentClassID param.Field[string]` environment_class_id specifies which environment class to use for the prebuild. If not specified, uses the project's default environment class. ### Returns - `type PrebuildNewResponse struct{…}` - `Prebuild Prebuild` Prebuild represents a prebuild for a project that creates a snapshot for faster environment startup times. - `Metadata PrebuildMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the prebuild was created - `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 string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `UpdatedAt Time` updated_at is when the prebuild was last updated - `EnvironmentClassID string` environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project's default environment class. - `Executor Subject` executor is the identity used to run the prebuild. The executor's SCM credentials are used to clone the repository. If not set, the creator's identity is used. - `OrganizationID string` organization_id is the ID of the organization that owns the prebuild - `ProjectID string` project_id is the ID of the project this prebuild was created for - `TriggeredBy PrebuildTrigger` trigger describes the trigger that created this prebuild. - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` - `Spec PrebuildSpec` spec contains the configuration used to create this prebuild - `DesiredPhase 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. - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Timeout string` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. - `Status PrebuildStatus` status contains the current status and progress of the prebuild - `Phase PrebuildPhase` phase is the current phase of the prebuild lifecycle - `CompletionTime Time` completion_time is when the prebuild completed (successfully or with failure) - `EnvironmentID string` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `FailureMessage string` failure_message contains details about why the prebuild failed - `LogURL string` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `SnapshotCompletionPercentage int64` snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider. - `SnapshotSizeBytes string` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `WarningMessage string` warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild. - `ID string` id is the unique identifier for the prebuild ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) prebuild, err := client.Prebuilds.New(context.TODO(), gitpod.PrebuildNewParams{ ProjectID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"), Spec: gitpod.F(gitpod.PrebuildSpecParam{ Timeout: gitpod.F("3600s"), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.Prebuilds.NewLogsToken(ctx, body) (*PrebuildNewLogsTokenResponse, error)` **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 - `body PrebuildNewLogsTokenParams` - `PrebuildID param.Field[string]` prebuild_id specifies the prebuild for which the logs token should be created. +required ### Returns - `type PrebuildNewLogsTokenResponse struct{…}` - `AccessToken string` access_token is the token that can be used to access the logs of the prebuild ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Prebuilds.NewLogsToken(context.TODO(), gitpod.PrebuildNewLogsTokenParams{ PrebuildID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.AccessToken) } ``` #### Response ```json { "accessToken": "accessToken" } ``` ## CreateWarmPool `client.Prebuilds.NewWarmPool(ctx, body) (*PrebuildNewWarmPoolResponse, error)` **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 - `body PrebuildNewWarmPoolParams` - `EnvironmentClassID param.Field[string]` environment_class_id specifies which environment class to warm. Must be listed in the project's prebuild configuration environment_class_ids. - `ProjectID param.Field[string]` project_id specifies the project this warm pool belongs to. The project must have prebuilds enabled. - `DesiredSize param.Field[int64]` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. - `MaxSize param.Field[int64]` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize param.Field[int64]` 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 - `type PrebuildNewWarmPoolResponse struct{…}` - `WarmPool WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `Metadata WarmPoolMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the warm pool was created - `UpdatedAt Time` updated_at is when the warm pool was last updated - `EnvironmentClassID string` environment_class_id is the environment class whose instances are warmed - `OrganizationID string` organization_id is the ID of the organization that owns the warm pool - `ProjectID string` project_id is the ID of the project this warm pool belongs to - `RunnerID string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `Spec WarmPoolSpec` spec contains the desired configuration for this warm pool - `DesiredPhase WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` - `DesiredSize int64` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `MaxSize int64` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize int64` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `SnapshotID string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Status WarmPoolStatus` status contains the current status reported by the runner - `Phase WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `DesiredSize int64` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `FailureMessage string` failure_message contains details about why the warm pool is degraded or failed - `RunningInstances int64` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `StoppedInstances int64` 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 string` id is the unique identifier for the warm pool ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Prebuilds.NewWarmPool(context.TODO(), gitpod.PrebuildNewWarmPoolParams{ EnvironmentClassID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), ProjectID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"), DesiredSize: gitpod.F(int64(2)), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.WarmPool) } ``` #### 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 `client.Prebuilds.Delete(ctx, body) (*PrebuildDeleteResponse, error)` **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 - `body PrebuildDeleteParams` - `PrebuildID param.Field[string]` prebuild_id specifies the prebuild to delete ### Returns - `type PrebuildDeleteResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) prebuild, err := client.Prebuilds.Delete(context.TODO(), gitpod.PrebuildDeleteParams{ PrebuildID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", prebuild) } ``` #### Response ```json {} ``` ## DeleteWarmPool `client.Prebuilds.DeleteWarmPool(ctx, body) (*PrebuildDeleteWarmPoolResponse, error)` **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 - `body PrebuildDeleteWarmPoolParams` - `WarmPoolID param.Field[string]` warm_pool_id specifies the warm pool to delete ### Returns - `type PrebuildDeleteWarmPoolResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Prebuilds.DeleteWarmPool(context.TODO(), gitpod.PrebuildDeleteWarmPoolParams{ WarmPoolID: gitpod.F("a1b2c3d4-5678-9abc-def0-1234567890ab"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` ## ListPrebuilds `client.Prebuilds.List(ctx, params) (*PrebuildsPage[Prebuild], error)` **post** `/gitpod.v1.PrebuildService/ListPrebuilds` ListPrebuilds ### Parameters - `params PrebuildListParams` - `Token param.Field[string]` Query param - `PageSize param.Field[int64]` Query param - `Filter param.Field[PrebuildListParamsFilter]` Body param: filter contains the filter options for listing prebuilds - `CreatorIDs []string` creator_ids filters prebuilds by who created them - `ExecutorIDs []string` executor_ids filters prebuilds by whose credentials were used to run them - `Phases []PrebuildPhase` phases filters prebuilds by their current phase - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `ProjectIDs []string` project_ids filters prebuilds to specific projects - `TriggeredBy []PrebuildTrigger` triggered_by filters prebuilds by how they were triggered - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` - `Pagination param.Field[PrebuildListParamsPagination]` Body param: pagination contains the pagination options for listing prebuilds - `Token string` Token for the next set of results that was returned as next_token of a PaginationResponse - `PageSize int64` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `type Prebuild struct{…}` Prebuild represents a prebuild for a project that creates a snapshot for faster environment startup times. - `Metadata PrebuildMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the prebuild was created - `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 string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `UpdatedAt Time` updated_at is when the prebuild was last updated - `EnvironmentClassID string` environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project's default environment class. - `Executor Subject` executor is the identity used to run the prebuild. The executor's SCM credentials are used to clone the repository. If not set, the creator's identity is used. - `OrganizationID string` organization_id is the ID of the organization that owns the prebuild - `ProjectID string` project_id is the ID of the project this prebuild was created for - `TriggeredBy PrebuildTrigger` trigger describes the trigger that created this prebuild. - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` - `Spec PrebuildSpec` spec contains the configuration used to create this prebuild - `DesiredPhase 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. - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Timeout string` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. - `Status PrebuildStatus` status contains the current status and progress of the prebuild - `Phase PrebuildPhase` phase is the current phase of the prebuild lifecycle - `CompletionTime Time` completion_time is when the prebuild completed (successfully or with failure) - `EnvironmentID string` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `FailureMessage string` failure_message contains details about why the prebuild failed - `LogURL string` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `SnapshotCompletionPercentage int64` snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider. - `SnapshotSizeBytes string` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `WarningMessage string` warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild. - `ID string` id is the unique identifier for the prebuild ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) page, err := client.Prebuilds.List(context.TODO(), gitpod.PrebuildListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 `client.Prebuilds.ListWarmPools(ctx, params) (*WarmPoolsPage[WarmPool], error)` **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 - `params PrebuildListWarmPoolsParams` - `Token param.Field[string]` Query param - `PageSize param.Field[int64]` Query param - `Filter param.Field[PrebuildListWarmPoolsParamsFilter]` Body param: filter contains the filter options for listing warm pools - `EnvironmentClassIDs []string` environment_class_ids filters warm pools to specific environment classes - `ProjectIDs []string` project_ids filters warm pools to specific projects - `Pagination param.Field[PrebuildListWarmPoolsParamsPagination]` Body param: pagination contains the pagination options for listing warm pools - `Token string` Token for the next set of results that was returned as next_token of a PaginationResponse - `PageSize int64` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `type WarmPool struct{…}` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `Metadata WarmPoolMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the warm pool was created - `UpdatedAt Time` updated_at is when the warm pool was last updated - `EnvironmentClassID string` environment_class_id is the environment class whose instances are warmed - `OrganizationID string` organization_id is the ID of the organization that owns the warm pool - `ProjectID string` project_id is the ID of the project this warm pool belongs to - `RunnerID string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `Spec WarmPoolSpec` spec contains the desired configuration for this warm pool - `DesiredPhase WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` - `DesiredSize int64` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `MaxSize int64` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize int64` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `SnapshotID string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Status WarmPoolStatus` status contains the current status reported by the runner - `Phase WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `DesiredSize int64` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `FailureMessage string` failure_message contains details about why the warm pool is degraded or failed - `RunningInstances int64` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `StoppedInstances int64` 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 string` id is the unique identifier for the warm pool ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) page, err := client.Prebuilds.ListWarmPools(context.TODO(), gitpod.PrebuildListWarmPoolsParams{ Filter: gitpod.F(gitpod.PrebuildListWarmPoolsParamsFilter{ ProjectIDs: gitpod.F([]string{"b0e12f6c-4c67-429d-a4a6-d9838b5da047"}), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 `client.Prebuilds.Get(ctx, body) (*PrebuildGetResponse, error)` **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 - `body PrebuildGetParams` - `PrebuildID param.Field[string]` prebuild_id specifies the prebuild to retrieve ### Returns - `type PrebuildGetResponse struct{…}` - `Prebuild Prebuild` Prebuild represents a prebuild for a project that creates a snapshot for faster environment startup times. - `Metadata PrebuildMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the prebuild was created - `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 string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `UpdatedAt Time` updated_at is when the prebuild was last updated - `EnvironmentClassID string` environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project's default environment class. - `Executor Subject` executor is the identity used to run the prebuild. The executor's SCM credentials are used to clone the repository. If not set, the creator's identity is used. - `OrganizationID string` organization_id is the ID of the organization that owns the prebuild - `ProjectID string` project_id is the ID of the project this prebuild was created for - `TriggeredBy PrebuildTrigger` trigger describes the trigger that created this prebuild. - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` - `Spec PrebuildSpec` spec contains the configuration used to create this prebuild - `DesiredPhase 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. - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Timeout string` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. - `Status PrebuildStatus` status contains the current status and progress of the prebuild - `Phase PrebuildPhase` phase is the current phase of the prebuild lifecycle - `CompletionTime Time` completion_time is when the prebuild completed (successfully or with failure) - `EnvironmentID string` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `FailureMessage string` failure_message contains details about why the prebuild failed - `LogURL string` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `SnapshotCompletionPercentage int64` snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider. - `SnapshotSizeBytes string` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `WarningMessage string` warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild. - `ID string` id is the unique identifier for the prebuild ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) prebuild, err := client.Prebuilds.Get(context.TODO(), gitpod.PrebuildGetParams{ PrebuildID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.Prebuilds.GetWarmPool(ctx, body) (*PrebuildGetWarmPoolResponse, error)` **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 - `body PrebuildGetWarmPoolParams` - `WarmPoolID param.Field[string]` warm_pool_id specifies the warm pool to retrieve ### Returns - `type PrebuildGetWarmPoolResponse struct{…}` - `WarmPool WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `Metadata WarmPoolMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the warm pool was created - `UpdatedAt Time` updated_at is when the warm pool was last updated - `EnvironmentClassID string` environment_class_id is the environment class whose instances are warmed - `OrganizationID string` organization_id is the ID of the organization that owns the warm pool - `ProjectID string` project_id is the ID of the project this warm pool belongs to - `RunnerID string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `Spec WarmPoolSpec` spec contains the desired configuration for this warm pool - `DesiredPhase WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` - `DesiredSize int64` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `MaxSize int64` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize int64` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `SnapshotID string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Status WarmPoolStatus` status contains the current status reported by the runner - `Phase WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `DesiredSize int64` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `FailureMessage string` failure_message contains details about why the warm pool is degraded or failed - `RunningInstances int64` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `StoppedInstances int64` 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 string` id is the unique identifier for the warm pool ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Prebuilds.GetWarmPool(context.TODO(), gitpod.PrebuildGetWarmPoolParams{ WarmPoolID: gitpod.F("a1b2c3d4-5678-9abc-def0-1234567890ab"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.WarmPool) } ``` #### 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 `client.Prebuilds.UpdateWarmPool(ctx, body) (*PrebuildUpdateWarmPoolResponse, error)` **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 - `body PrebuildUpdateWarmPoolParams` - `WarmPoolID param.Field[string]` warm_pool_id specifies the warm pool to update - `DesiredSize param.Field[int64]` desired_size updates the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. - `MaxSize param.Field[int64]` max_size updates the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize param.Field[int64]` 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 - `type PrebuildUpdateWarmPoolResponse struct{…}` - `WarmPool WarmPool` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `Metadata WarmPoolMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the warm pool was created - `UpdatedAt Time` updated_at is when the warm pool was last updated - `EnvironmentClassID string` environment_class_id is the environment class whose instances are warmed - `OrganizationID string` organization_id is the ID of the organization that owns the warm pool - `ProjectID string` project_id is the ID of the project this warm pool belongs to - `RunnerID string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `Spec WarmPoolSpec` spec contains the desired configuration for this warm pool - `DesiredPhase WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` - `DesiredSize int64` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `MaxSize int64` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize int64` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `SnapshotID string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Status WarmPoolStatus` status contains the current status reported by the runner - `Phase WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `DesiredSize int64` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `FailureMessage string` failure_message contains details about why the warm pool is degraded or failed - `RunningInstances int64` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `StoppedInstances int64` 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 string` id is the unique identifier for the warm pool ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Prebuilds.UpdateWarmPool(context.TODO(), gitpod.PrebuildUpdateWarmPoolParams{ WarmPoolID: gitpod.F("a1b2c3d4-5678-9abc-def0-1234567890ab"), DesiredSize: gitpod.F(int64(5)), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.WarmPool) } ``` #### 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 - `type Prebuild struct{…}` Prebuild represents a prebuild for a project that creates a snapshot for faster environment startup times. - `Metadata PrebuildMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the prebuild was created - `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 string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `UpdatedAt Time` updated_at is when the prebuild was last updated - `EnvironmentClassID string` environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project's default environment class. - `Executor Subject` executor is the identity used to run the prebuild. The executor's SCM credentials are used to clone the repository. If not set, the creator's identity is used. - `OrganizationID string` organization_id is the ID of the organization that owns the prebuild - `ProjectID string` project_id is the ID of the project this prebuild was created for - `TriggeredBy PrebuildTrigger` trigger describes the trigger that created this prebuild. - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` - `Spec PrebuildSpec` spec contains the configuration used to create this prebuild - `DesiredPhase 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. - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Timeout string` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. - `Status PrebuildStatus` status contains the current status and progress of the prebuild - `Phase PrebuildPhase` phase is the current phase of the prebuild lifecycle - `CompletionTime Time` completion_time is when the prebuild completed (successfully or with failure) - `EnvironmentID string` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `FailureMessage string` failure_message contains details about why the prebuild failed - `LogURL string` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `SnapshotCompletionPercentage int64` snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider. - `SnapshotSizeBytes string` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `WarningMessage string` warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild. - `ID string` id is the unique identifier for the prebuild ### Prebuild Metadata - `type PrebuildMetadata struct{…}` PrebuildMetadata contains metadata about the prebuild - `CreatedAt Time` 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 string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `UpdatedAt Time` updated_at is when the prebuild was last updated - `EnvironmentClassID string` environment_class_id is the environment class used to create this prebuild. While the prebuild is created with a specific environment class, environments with different classes (e.g., smaller or larger instance sizes) can be created from the same prebuild, as long as they run on the same runner. If not specified in create requests, uses the project's default environment class. - `Executor Subject` executor is the identity used to run the prebuild. The executor's SCM credentials are used to clone the repository. If not set, the creator's identity is used. - `OrganizationID string` organization_id is the ID of the organization that owns the prebuild - `ProjectID string` project_id is the ID of the project this prebuild was created for - `TriggeredBy PrebuildTrigger` trigger describes the trigger that created this prebuild. - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` ### Prebuild Phase - `type PrebuildPhase string` PrebuildPhase represents the lifecycle phase of a prebuild - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` ### Prebuild Spec - `type PrebuildSpec struct{…}` PrebuildSpec contains the configuration used to create a prebuild - `DesiredPhase 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. - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Timeout string` timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. ### Prebuild Status - `type PrebuildStatus struct{…}` PrebuildStatus contains the current status and progress of a prebuild - `Phase PrebuildPhase` phase is the current phase of the prebuild lifecycle - `const PrebuildPhaseUnspecified PrebuildPhase = "PREBUILD_PHASE_UNSPECIFIED"` - `const PrebuildPhasePending PrebuildPhase = "PREBUILD_PHASE_PENDING"` - `const PrebuildPhaseStarting PrebuildPhase = "PREBUILD_PHASE_STARTING"` - `const PrebuildPhaseRunning PrebuildPhase = "PREBUILD_PHASE_RUNNING"` - `const PrebuildPhaseStopping PrebuildPhase = "PREBUILD_PHASE_STOPPING"` - `const PrebuildPhaseSnapshotting PrebuildPhase = "PREBUILD_PHASE_SNAPSHOTTING"` - `const PrebuildPhaseCompleted PrebuildPhase = "PREBUILD_PHASE_COMPLETED"` - `const PrebuildPhaseFailed PrebuildPhase = "PREBUILD_PHASE_FAILED"` - `const PrebuildPhaseCancelling PrebuildPhase = "PREBUILD_PHASE_CANCELLING"` - `const PrebuildPhaseCancelled PrebuildPhase = "PREBUILD_PHASE_CANCELLED"` - `const PrebuildPhaseDeleting PrebuildPhase = "PREBUILD_PHASE_DELETING"` - `const PrebuildPhaseDeleted PrebuildPhase = "PREBUILD_PHASE_DELETED"` - `CompletionTime Time` completion_time is when the prebuild completed (successfully or with failure) - `EnvironmentID string` environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. - `FailureMessage string` failure_message contains details about why the prebuild failed - `LogURL string` log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. - `SnapshotCompletionPercentage int64` snapshot_completion_percentage is the progress of snapshot creation (0-100). Only populated when phase is SNAPSHOTTING and progress is available from the cloud provider. This value may update infrequently or remain at 0 depending on the provider. - `SnapshotSizeBytes string` snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED). - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `WarningMessage string` warning_message contains warnings from the prebuild environment that indicate something went wrong but the prebuild could still complete. For example, the devcontainer failed to build but the environment is still usable. These warnings will likely affect any environment started from this prebuild. ### Prebuild Trigger - `type PrebuildTrigger string` PrebuildTrigger indicates how the prebuild was triggered - `const PrebuildTriggerUnspecified PrebuildTrigger = "PREBUILD_TRIGGER_UNSPECIFIED"` - `const PrebuildTriggerManual PrebuildTrigger = "PREBUILD_TRIGGER_MANUAL"` - `const PrebuildTriggerScheduled PrebuildTrigger = "PREBUILD_TRIGGER_SCHEDULED"` ### Warm Pool - `type WarmPool struct{…}` WarmPool maintains pre-created environment instances from a prebuild snapshot for near-instant environment startup. One warm pool exists per pair. - `Metadata WarmPoolMetadata` metadata contains organizational and ownership information - `CreatedAt Time` created_at is when the warm pool was created - `UpdatedAt Time` updated_at is when the warm pool was last updated - `EnvironmentClassID string` environment_class_id is the environment class whose instances are warmed - `OrganizationID string` organization_id is the ID of the organization that owns the warm pool - `ProjectID string` project_id is the ID of the project this warm pool belongs to - `RunnerID string` runner_id is the runner that manages this warm pool. Derived from the environment class. - `Spec WarmPoolSpec` spec contains the desired configuration for this warm pool - `DesiredPhase WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` - `DesiredSize int64` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `MaxSize int64` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize int64` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `SnapshotID string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. - `Status WarmPoolStatus` status contains the current status reported by the runner - `Phase WarmPoolPhase` phase is the current phase of the warm pool lifecycle - `DesiredSize int64` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `FailureMessage string` failure_message contains details about why the warm pool is degraded or failed - `RunningInstances int64` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `StoppedInstances int64` 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 string` id is the unique identifier for the warm pool ### Warm Pool Metadata - `type WarmPoolMetadata struct{…}` WarmPoolMetadata contains metadata about the warm pool - `CreatedAt Time` created_at is when the warm pool was created - `UpdatedAt Time` updated_at is when the warm pool was last updated - `EnvironmentClassID string` environment_class_id is the environment class whose instances are warmed - `OrganizationID string` organization_id is the ID of the organization that owns the warm pool - `ProjectID string` project_id is the ID of the project this warm pool belongs to - `RunnerID string` runner_id is the runner that manages this warm pool. Derived from the environment class. ### Warm Pool Phase - `type WarmPoolPhase string` WarmPoolPhase represents the lifecycle phase of a warm pool - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` ### Warm Pool Spec - `type WarmPoolSpec struct{…}` WarmPoolSpec contains the desired configuration for a warm pool - `DesiredPhase WarmPoolPhase` desired_phase is the intended lifecycle phase for this warm pool. Managed by the API and reconciler. - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` - `DesiredSize int64` desired_size is the number of warm instances to maintain. Deprecated: Use min_size and max_size instead for dynamic scaling. Existing pools will be migrated to min_size=max_size=desired_size. - `MaxSize int64` max_size is the maximum number of warm instances to maintain. The pool will never scale above this value. Must be >= min_size and <= 20. - `MinSize int64` min_size is the minimum number of warm instances to maintain. The pool will never scale below this value. Must be >= 0 and <= max_size. Set to 0 to allow full scale-down. - `SnapshotID string` snapshot_id is the prebuild snapshot to warm up in the pool. Updated by the reconciler when a new prebuild completes for this project and environment class. Empty when no completed prebuild exists yet. - `SpecVersion string` spec_version is incremented each time the spec is updated. Used for optimistic concurrency control. ### Warm Pool Status - `type WarmPoolStatus struct{…}` 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 - `const WarmPoolPhaseUnspecified WarmPoolPhase = "WARM_POOL_PHASE_UNSPECIFIED"` - `const WarmPoolPhasePending WarmPoolPhase = "WARM_POOL_PHASE_PENDING"` - `const WarmPoolPhaseReady WarmPoolPhase = "WARM_POOL_PHASE_READY"` - `const WarmPoolPhaseDegraded WarmPoolPhase = "WARM_POOL_PHASE_DEGRADED"` - `const WarmPoolPhaseDeleting WarmPoolPhase = "WARM_POOL_PHASE_DELETING"` - `const WarmPoolPhaseDeleted WarmPoolPhase = "WARM_POOL_PHASE_DELETED"` - `DesiredSize int64` desired_size is the current target number of instances the autoscaler has decided on. Unlike running_instances, this value is stable and does not fluctuate as instances are claimed and backfilled. - `FailureMessage string` failure_message contains details about why the warm pool is degraded or failed - `RunningInstances int64` running_instances is the number of running warm instances in the pool, ready to be claimed for near-instant environment startup. - `StatusVersion string` status_version is incremented each time the status is updated. Used for optimistic concurrency control. - `StoppedInstances int64` 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.