Create Project

Unary · Projects 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.

name: "Web Application"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/repo"

Create project with devcontainer: Creates a project with custom development container.

name: "Backend Service"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/backend"
devcontainerFilePath: ".devcontainer/devcontainer.json"
automationsFilePath: ".gitpod/automations.yaml"

Endpoint

POST /api/gitpod.v1.ProjectService/CreateProject

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.ProjectService/CreateProject" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "initializer": {
    "specs": [
      {
        "git": {
          "remoteUri": "https://example.com"
        }
      }
    ]
  }
}'

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)

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);

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)
}

{
  "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	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	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	No

EnvironmentInitializer

EnvironmentInitializer specifies how an environment is to be initializedgitpod.v1.EnvironmentInitializer

Field	Type	Required	Description
`specs`	array of Spec	No

Spec

gitpod.v1.EnvironmentInitializer.Spec

Field	Type	Required	Description
`git`	GitInitializer	One of `spec`
`contextUrl`	ContextURLInitializer	One of `spec`

PrebuildTrigger

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.

Project

gitpod.v1.Project

Field	Type	Required	Description
`id`	string	No	id is the unique identifier for the project Constraints: `string.uuid=true`.
`metadata`	ProjectMetadata	No
`initializer`	EnvironmentInitializer	No	initializer is the content initializer
`environmentClass`	ProjectEnvironmentClass	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	No	environment_classes is the list of environment classes for the project
`usedBy`	UsedBy	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	No	prebuild_configuration defines how prebuilds are created for this project.
`desiredPhase`	ProjectPhase	No	desired_phase is the desired phase of the project When set to DELETED, the project is pending deletion
`recommendedEditors`	RecommendedEditors	No	recommended_editors specifies the editors recommended for this project.

UsedBy

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

ProjectEnvironmentClass

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

ProjectMetadata

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

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	No	trigger defines when prebuilds should be created.
`executor`	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

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”: {}}

Subject

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	No	Principal is the principal of the subject Constraints: `enum.defined_only=true`.

Principal

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

ProjectPhase

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

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