Create Projects

Unary · Projects Creates multiple projects in a single request. Use this method to:

Onboard multiple repositories at once
Import a batch of projects during initial setup

Returns successfully created projects and details about any failures. Each project in the request is processed independently - partial success is possible.

Examples

Create multiple projects: Creates several projects in one request.

projects:
  - name: "Frontend"
    initializer:
      specs:
        - git:
            remoteUri: "https://github.com/org/frontend"
  - name: "Backend"
    initializer:
      specs:
        - git:
            remoteUri: "https://github.com/org/backend"

Endpoint

POST /api/gitpod.v1.ProjectService/CreateProjects

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/CreateProjects" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "projects": [
    {
      "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.CreateProjectsRequest(
    projects=[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_projects(request)
print(response)

import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreateProjectsRequestSchema } from "@gitpod/sdk/gitpod/v1/project_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(CreateProjectsRequestSchema, {
    projects: [{
      initializer: {
        specs: [{
          spec: {
            case: "git",
            value: {
              remoteUri: "https://example.com",
            },
          },
        }],
      },
    }],
  });
  const response = await ona.services.project.createProjects(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.CreateProjectsRequest{
		Projects: []*gitpodpb.CreateProjectRequest{&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.CreateProjects(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "projects": [
    {
      "initializer": {
        "specs": [
          {
            "git": {
              "remoteUri": "https://example.com"
            }
          }
        ]
      }
    }
  ]
}

Request

gitpod.v1.CreateProjectsRequest

Field	Type	Required	Description
`projects`	array of CreateProjectRequest	No	Constraints: `repeated.max_items=100, repeated.min_items=1`.

Response

gitpod.v1.CreateProjectsResponse

Field	Type	Required	Description
`createdProjects`	array of Project	No	created_projects contains the successfully created projects
`failedProjects`	array of Failure	No	failed_projects contains details about projects that failed to create

CreateProjectRequest

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.

Failure

gitpod.v1.CreateProjectsResponse.Failure

Field	Type	Required	Description
`index`	integer	No	index is the position in the request array (0-based)
`name`	string	No	name is the project name that failed
`error`	string	No	error describes why the project creation failed

EnvironmentInitializer

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

Field	Type	Required	Description
`specs`	array of Spec	No

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

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