Create Prebuild

Unary · Prebuilds Creates a prebuild for a project. Use this method to:

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

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

Examples

Create basic prebuild: Creates a prebuild for a project using default settings.

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

Create prebuild with custom environment class: Creates a prebuild with a specific environment class and timeout.

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

Endpoint

POST /api/gitpod.v1.PrebuildService/CreatePrebuild

Send a Bearer token as described in Authentication. If your organization uses a custom management-plane domain, replace https://app.ona.com with that domain.

Request example

export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.PrebuildService/CreatePrebuild" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "projectId": "<project-id>",
  "spec": {
    "specVersion": "1"
  }
}'

import gitpod.v1.prebuild_pb2 as prebuild_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = prebuild_pb2.CreatePrebuildRequest(
    project_id="<project-id>",
    spec=prebuild_pb2.PrebuildSpec(
        spec_version=1,
    ),
)
response = ona.services.prebuild.create_prebuild(request)
print(response)

import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreatePrebuildRequestSchema } from "@gitpod/sdk/gitpod/v1/prebuild_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(CreatePrebuildRequestSchema, {
    projectId: "<project-id>",
    spec: {
      specVersion: 1n,
    },
  });
  const response = await ona.services.prebuild.createPrebuild(request);
  console.log(response);
}

main().catch(console.error);

package main

import (
	"context"
	"fmt"
	"log"

	"connectrpc.com/connect"
	"github.com/gitpod-io/gitpod-sdk-go/sdk"
	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)

func main() {
	ona, err := sdk.NewFromEnv()
	if err != nil {
		log.Fatal(err)
	}

	request := connect.NewRequest(&gitpodpb.CreatePrebuildRequest{
		ProjectId: "<project-id>",
		Spec: &gitpodpb.PrebuildSpec{
			SpecVersion: 1,
		},
	})
	response, err := ona.Services.Prebuild.CreatePrebuild(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "projectId": "<project-id>",
  "spec": {
    "specVersion": "1"
  }
}

Request

gitpod.v1.CreatePrebuildRequest

Field	Type	Required	Description
`projectId`	string	Yes	project_id specifies the project to create a prebuild for Constraints: `required=true, string.uuid=true`.
`environmentClassId`	string	No	environment_class_id specifies which environment class to use for the prebuild. If not specified, uses the project’s default environment class. Constraints: `string.uuid=true`.
`spec`	PrebuildSpec	Yes	spec contains the configuration for creating the prebuild Constraints: `required=true`.

Response

gitpod.v1.CreatePrebuildResponse

Field	Type	Required	Description
`prebuild`	Prebuild	Yes	Constraints: `required=true`.

Prebuild

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

Field	Type	Required	Description
`id`	string	No	id is the unique identifier for the prebuild Constraints: `string.uuid=true`.
`metadata`	PrebuildMetadata	Yes	metadata contains organizational and ownership information Constraints: `required=true`.
`spec`	PrebuildSpec	Yes	spec contains the configuration used to create this prebuild Constraints: `required=true`.
`status`	PrebuildStatus	Yes	status contains the current status and progress of the prebuild Constraints: `required=true`.

PrebuildMetadata

PrebuildMetadata contains metadata about the prebuildgitpod.v1.PrebuildMetadata

Field	Type	Required	Description
`organizationId`	string	No	organization_id is the ID of the organization that owns the prebuild Constraints: `string.uuid=true`.
`projectId`	string	No	project_id is the ID of the project this prebuild was created for Constraints: `string.uuid=true`.
`environmentClassId`	string	No	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. Constraints: `string.uuid=true`.
`creator`	Subject	Yes	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. Constraints: `required=true`.
`createdAt`	RFC 3339 timestamp	Yes	created_at is when the prebuild was created Constraints: `required=true`.
`updatedAt`	RFC 3339 timestamp	Yes	updated_at is when the prebuild was last updated Constraints: `required=true`.
`triggeredBy`	PrebuildTrigger	No	trigger describes the trigger that created this prebuild. Constraints: `enum.defined_only=true`.
`executor`	Subject	No	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.

PrebuildSpec

PrebuildSpec contains the configuration used to create a prebuildgitpod.v1.PrebuildSpec

Field	Type	Required	Description
`specVersion`	64-bit integer string	No	spec_version is incremented each time the spec is updated. Used for optimistic concurrency control.
`desiredPhase`	PrebuildPhase	No	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. Constraints: `enum.defined_only=true`.
`timeout`	duration string	No	timeout is the maximum time allowed for the prebuild to complete. Defaults to 60 minutes if not specified. Maximum allowed timeout is 2 hours. Constraints: `duration.gte.seconds=300, duration.lte.seconds=7200`.

PrebuildStatus

PrebuildStatus contains the current status and progress of a prebuildgitpod.v1.PrebuildStatus

Field	Type	Required	Description
`phase`	PrebuildPhase	Yes	phase is the current phase of the prebuild lifecycle Constraints: `enum.defined_only=true, required=true`.
`completionTime`	RFC 3339 timestamp	No	completion_time is when the prebuild completed (successfully or with failure)
`failureMessage`	string	No	failure_message contains details about why the prebuild failed
`logUrl`	string	No	log_url provides access to prebuild logs. During prebuild execution, this references the environment logs. After completion, this may reference archived logs. Constraints: `string.uri=true`.
`environmentId`	string	No	environment_id is the ID of the environment used to create this prebuild. This field is set when the prebuild environment is created. Constraints: `string.uuid=true`.
`statusVersion`	64-bit integer string	No	status_version is incremented each time the status is updated. Used for optimistic concurrency control.
`warningMessage`	string	No	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.
`snapshotCompletionPercentage`	integer	No	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. Constraints: `int32.gte=0, int32.lte=100`.
`snapshotSizeBytes`	64-bit integer string	No	snapshot_size_bytes is the size of the snapshot in bytes. Only populated when the snapshot is available (phase is COMPLETED).

PrebuildTrigger

PrebuildTrigger indicates how the prebuild was triggered

Value	Number	Description
`PREBUILD_TRIGGER_UNSPECIFIED`	0	PREBUILD_TRIGGER_UNSPECIFIED is the default value and should not be used
`PREBUILD_TRIGGER_MANUAL`	1	PREBUILD_TRIGGER_MANUAL indicates the prebuild was manually triggered by a user
`PREBUILD_TRIGGER_SCHEDULED`	2	PREBUILD_TRIGGER_SCHEDULED indicates the prebuild was triggered by a scheduled job

PrebuildPhase

PrebuildPhase represents the lifecycle phase of a prebuild

Value	Number	Description
`PREBUILD_PHASE_UNSPECIFIED`	0	PREBUILD_PHASE_UNSPECIFIED is the default value and should not be used
`PREBUILD_PHASE_PENDING`	10	PREBUILD_PHASE_PENDING indicates the prebuild has been created but the environment has not yet started
`PREBUILD_PHASE_STARTING`	20	PREBUILD_PHASE_STARTING indicates the prebuild is being started
`PREBUILD_PHASE_RUNNING`	30	PREBUILD_PHASE_RUNNING indicates the prebuild is running and tasks are executing
`PREBUILD_PHASE_STOPPING`	40	PREBUILD_PHASE_STOPPING indicates the prebuild is being stopped after completion
`PREBUILD_PHASE_SNAPSHOTTING`	50	PREBUILD_PHASE_SNAPSHOTTING indicates the environment has stopped and a snapshot is being created
`PREBUILD_PHASE_COMPLETED`	60	PREBUILD_PHASE_COMPLETED indicates the prebuild completed successfully and the snapshot is available
`PREBUILD_PHASE_FAILED`	70	PREBUILD_PHASE_FAILED indicates the prebuild failed at any stage
`PREBUILD_PHASE_CANCELLING`	75	PREBUILD_PHASE_CANCELLING indicates the prebuild is being cancelled (cleanup in progress)
`PREBUILD_PHASE_CANCELLED`	80	PREBUILD_PHASE_CANCELLED indicates the prebuild was manually cancelled
`PREBUILD_PHASE_DELETING`	85	PREBUILD_PHASE_DELETING indicates the prebuild is being deleted (cleanup in progress)
`PREBUILD_PHASE_DELETED`	90	PREBUILD_PHASE_DELETED indicates the prebuild is being deleted

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Examples

Endpoint

Request example

Request

Response

​Examples

​Endpoint

​Request example

​Request

​Response

​Related types

Examples

Endpoint

Request example

Request

Response

Related types