> ## 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 Project
> Creates a new project with specified configuration.
`Unary` ยท [`Projects`](/docs/api-reference/generated/project/overview)
Creates a new project with specified configuration.
Use this method to:
* Set up development projects
* Configure project environments
* Define project settings
* Initialize project content
### Examples
* Create basic project:
Creates a project with minimal configuration.
```yaml theme={null}
name: "Web Application"
initializer:
specs:
- git:
remoteUri: "https://github.com/org/repo"
```
* Create project with devcontainer:
Creates a project with custom development container.
```yaml theme={null}
name: "Backend Service"
initializer:
specs:
- git:
remoteUri: "https://github.com/org/backend"
devcontainerFilePath: ".devcontainer/devcontainer.json"
automationsFilePath: ".gitpod/automations.yaml"
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.ProjectService/CreateProject
```
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.ProjectService/CreateProject" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"initializer": {
"specs": [
{
"git": {
"remoteUri": "https://example.com"
}
}
]
}
}'
```
```python Python theme={null}
import gitpod.v1.environment_pb2 as environment_pb2
import gitpod.v1.project_pb2 as project_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = project_pb2.CreateProjectRequest(
initializer=environment_pb2.EnvironmentInitializer(
specs=[environment_pb2.EnvironmentInitializer.Spec(
git=environment_pb2.GitInitializer(
remote_uri="https://example.com",
),
)],
),
)
response = ona.services.project.create_project(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreateProjectRequestSchema } from "@gitpod/sdk/gitpod/v1/project_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(CreateProjectRequestSchema, {
initializer: {
specs: [{
spec: {
case: "git",
value: {
remoteUri: "https://example.com",
},
},
}],
},
});
const response = await ona.services.project.createProject(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.CreateProjectRequest{
Initializer: &gitpodpb.EnvironmentInitializer{
Specs: []*gitpodpb.EnvironmentInitializer_Spec{&gitpodpb.EnvironmentInitializer_Spec{
Spec: &gitpodpb.EnvironmentInitializer_Spec_Git{
Git: &gitpodpb.GitInitializer{
RemoteUri: "https://example.com",
},
},
}},
},
})
response, err := ona.Services.Project.CreateProject(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"initializer": {
"specs": [
{
"git": {
"remoteUri": "https://example.com"
}
}
]
}
}
```
## Request
`gitpod.v1.CreateProjectRequest`
| Field | Type | Required | Description |
| ----------------------- | ------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | No | Constraints: `string.max_len=80, string.min_len=1`. |
| `initializer` | [EnvironmentInitializer](#type-gitpod-v1-environment-initializer) | Yes | initializer is the content initializer Constraints: `required=true`. |
| `devcontainerFilePath` | string | No | devcontainer\_file\_path is the path to the devcontainer file relative to the repo root Constraints: `cel.expression=this.matches('^$\|^[^/].*'), cel.id=relative_path, cel.message=path must not be absolute (start with a /)`. |
| `automationsFilePath` | string | No | automations\_file\_path is the path to the automations file relative to the repo root Constraints: `cel.expression=this.matches('^$\|^[^/].*'), cel.id=relative_path, cel.message=path must not be absolute (start with a /)`. |
| `technicalDescription` | string | No | technical\_description is a detailed technical description of the project This field is not returned by default in GetProject or ListProjects responses Constraints: `string.max_len=8192`. |
| `prebuildConfiguration` | [ProjectPrebuildConfiguration](#type-gitpod-v1-project-prebuild-configuration) | No | prebuild\_configuration defines how prebuilds are created for this project. If not set, prebuilds are disabled for the project. |
## Response
`gitpod.v1.CreateProjectResponse`
| Field | Type | Required | Description |
| --------- | ---------------------------------- | -------- | ----------- |
| `project` | [Project](#type-gitpod-v1-project) | No | |
## Related types
EnvironmentInitializer specifies how an environment is to be initialized
`gitpod.v1.EnvironmentInitializer`
| Field | Type | Required | Description |
| ------- | ------------------------------------------------------------- | -------- | ----------- |
| `specs` | array of [Spec](#type-gitpod-v1-environment-initializer-spec) | No | |
`gitpod.v1.EnvironmentInitializer.Spec`
| Field | Type | Required | Description |
| ------------ | --------------------- | ------------- | ----------- |
| `git` | GitInitializer | One of `spec` | |
| `contextUrl` | ContextURLInitializer | One of `spec` | |
PrebuildTrigger defines when prebuilds should be created for a project.
`gitpod.v1.PrebuildTrigger`
| Field | Type | Required | Description |
| --------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dailySchedule` | DailySchedule | No | daily\_schedule triggers a prebuild once per day at the specified hour (UTC). The actual start time may vary slightly to distribute system load. |
`gitpod.v1.Project`
| Field | Type | Required | Description |
| ----------------------- | ------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | No | id is the unique identifier for the project Constraints: `string.uuid=true`. |
| `metadata` | [ProjectMetadata](#type-gitpod-v1-project-metadata) | No | |
| `initializer` | [EnvironmentInitializer](#type-gitpod-v1-environment-initializer) | No | initializer is the content initializer |
| `environmentClass` | [ProjectEnvironmentClass](#type-gitpod-v1-project-environment-class) | Yes | **Deprecated.** Use `environment_classes` instead. Constraints: `required=true`. |
| `devcontainerFilePath` | string | No | devcontainer\_file\_path is the path to the devcontainer file relative to the repo root |
| `environmentClasses` | array of [ProjectEnvironmentClass](#type-gitpod-v1-project-environment-class) | No | environment\_classes is the list of environment classes for the project |
| `usedBy` | [UsedBy](#type-gitpod-v1-project-used-by) | No | |
| `automationsFilePath` | string | No | automations\_file\_path is the path to the automations file relative to the repo root |
| `technicalDescription` | string | No | technical\_description is a detailed technical description of the project This field is not returned by default in GetProject or ListProjects responses |
| `prebuildConfiguration` | [ProjectPrebuildConfiguration](#type-gitpod-v1-project-prebuild-configuration) | No | prebuild\_configuration defines how prebuilds are created for this project. |
| `desiredPhase` | [ProjectPhase](#enum-gitpod-v1-project-phase) | No | desired\_phase is the desired phase of the project When set to DELETED, the project is pending deletion |
| `recommendedEditors` | [RecommendedEditors](#type-gitpod-v1-recommended-editors) | No | recommended\_editors specifies the editors recommended for this project. |
`gitpod.v1.Project.UsedBy`
| Field | Type | Required | Description |
| --------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------- |
| `subjects` | array of Subject | No | Subjects are the 10 most recent subjects who have used the project to create an environment |
| `totalSubjects` | integer | No | Total number of unique subjects who have used the project |
`gitpod.v1.ProjectEnvironmentClass`
| Field | Type | Required | Description |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `localRunner` | boolean | No | Use a local runner for the user |
| `environmentClassId` | string | No | Use a fixed environment class on a given Runner. This cannot be a local runner's environment class. Constraints: `string.uuid=true`. |
| `order` | integer | No | order is the priority of this entry |
`gitpod.v1.ProjectMetadata`
| Field | Type | Required | Description |
| ---------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `organizationId` | string | No | organization\_id is the ID of the organization that contains the environment Constraints: `string.uuid=true`. |
| `name` | string | No | name is the human readable name of the project Constraints: `string.max_len=80, string.min_len=1`. |
| `creator` | Subject | No | creator is the identity of the project creator |
| `createdAt` | RFC 3339 timestamp | No | |
| `updatedAt` | RFC 3339 timestamp | No | |
ProjectPrebuildConfiguration defines how prebuilds are created for a project.
Prebuilds create environment snapshots that enable faster environment startup times.
`gitpod.v1.ProjectPrebuildConfiguration`
| Field | Type | Required | Description |
| ----------------------- | --------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | No | enabled controls whether prebuilds are created for this project. When disabled, no automatic prebuilds will be triggered. |
| `environmentClassIds` | array of string | No | environment\_class\_ids specifies which environment classes should have prebuilds created. If empty, no prebuilds are created. Constraints: `repeated.items.string.uuid=true`. |
| `timeout` | duration string | No | timeout is the maximum duration allowed for a prebuild to complete. If not specified, defaults to 1 hour. Must be between 5 minutes and 2 hours. Constraints: `duration.gte.seconds=300, duration.lte.seconds=7200`. |
| `trigger` | [PrebuildTrigger](#type-gitpod-v1-prebuild-trigger) | No | trigger defines when prebuilds should be created. |
| `executor` | [Subject](#type-gitpod-v1-subject) | No | executor specifies who runs prebuilds for this project. The executor's SCM credentials are used to clone the repository. If not set, defaults to the project creator. |
| `enableJetbrainsWarmup` | boolean | No | enable\_jetbrains\_warmup controls whether JetBrains IDE warmup runs during prebuilds. |
RecommendedEditors contains the map of recommended editors and their versions.
`gitpod.v1.RecommendedEditors`
| Field | Type | Required | Description |
| --------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `editors` | map of string to EditorVersions | No | editors maps editor aliases to their recommended versions. Key is the editor alias (e.g., "intellij", "goland", "vscode"). Value contains the list of recommended versions for that editor. If versions list is empty, all available versions are recommended. Example: \{"intellij": \{versions: \["2025.1", "2024.3"]}, "goland": \{}} |
`gitpod.v1.Subject`
| Field | Type | Required | Description |
| ----------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------- |
| `id` | string | No | id is the UUID of the subject Constraints: `ignore=1, string.uuid=true`. |
| `principal` | [Principal](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. |
| Value | Number | Description |
| --------------------------- | -----: | ----------- |
| `PRINCIPAL_UNSPECIFIED` | 0 | |
| `PRINCIPAL_ACCOUNT` | 1 | |
| `PRINCIPAL_USER` | 2 | |
| `PRINCIPAL_RUNNER` | 3 | |
| `PRINCIPAL_ENVIRONMENT` | 4 | |
| `PRINCIPAL_SERVICE_ACCOUNT` | 5 | |
| `PRINCIPAL_RUNNER_MANAGER` | 6 | |
| Value | Number | Description |
| --------------------------- | -----: | --------------------------------------------------------------------- |
| `PROJECT_PHASE_UNSPECIFIED` | 0 | |
| `PROJECT_PHASE_ACTIVE` | 1 | The project is active and can be used |
| `PROJECT_PHASE_DELETED` | 2 | The project is marked for deletion and prebuilds are being cleaned up |