> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Prebuild
> Creates a prebuild for a project.
`Unary` ยท [`Prebuilds`](/docs/api-reference/generated/prebuild/overview)
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 theme={null}
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 theme={null}
projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
spec:
timeout: "3600s" # 1 hour
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.PrebuildService/CreatePrebuild
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.PrebuildService/CreatePrebuild" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"projectId": "",
"spec": {
"specVersion": "1"
}
}'
```
```python Python theme={null}
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="",
spec=prebuild_pb2.PrebuildSpec(
spec_version=1,
),
)
response = ona.services.prebuild.create_prebuild(request)
print(response)
```
```typescript TypeScript theme={null}
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: "",
spec: {
specVersion: 1n,
},
});
const response = await ona.services.prebuild.createPrebuild(request);
console.log(response);
}
main().catch(console.error);
```
```go Go theme={null}
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: "",
Spec: &gitpodpb.PrebuildSpec{
SpecVersion: 1,
},
})
response, err := ona.Services.Prebuild.CreatePrebuild(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"projectId": "",
"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](#type-gitpod-v1-prebuild-spec) | Yes | spec contains the configuration for creating the prebuild Constraints: `required=true`. |
## Response
`gitpod.v1.CreatePrebuildResponse`
| Field | Type | Required | Description |
| ---------- | ------------------------------------ | -------- | ----------------------------- |
| `prebuild` | [Prebuild](#type-gitpod-v1-prebuild) | Yes | Constraints: `required=true`. |
## Related types
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](#type-gitpod-v1-prebuild-metadata) | Yes | metadata contains organizational and ownership information Constraints: `required=true`. |
| `spec` | [PrebuildSpec](#type-gitpod-v1-prebuild-spec) | Yes | spec contains the configuration used to create this prebuild Constraints: `required=true`. |
| `status` | [PrebuildStatus](#type-gitpod-v1-prebuild-status) | Yes | status contains the current status and progress of the prebuild Constraints: `required=true`. |
PrebuildMetadata contains metadata about the prebuild
`gitpod.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](#enum-gitpod-v1-prebuild-metadata-prebuild-trigger) | 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 contains the configuration used to create a prebuild
`gitpod.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](#enum-gitpod-v1-prebuild-phase) | 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 contains the current status and progress of a prebuild
`gitpod.v1.PrebuildStatus`
| Field | Type | Required | Description |
| ------------------------------ | ----------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `phase` | [PrebuildPhase](#enum-gitpod-v1-prebuild-phase) | 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 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 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 |