Create Project From Environment

Unary · Projects Creates a new project using an existing environment as a template. Use this method to:

Clone environment configurations
Create projects from templates
Share environment setups

Examples

Create from environment: Creates a project based on existing environment.

name: "Frontend Project"
environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"

Endpoint

POST /api/gitpod.v1.ProjectService/CreateProjectFromEnvironment

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/CreateProjectFromEnvironment" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "<name>"
}'

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

ona = create_client_from_env()
request = project_pb2.CreateProjectFromEnvironmentRequest(
    name="<name>",
)
response = ona.services.project.create_project_from_environment(request)
print(response)

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

async function main() {
  const ona = createClientFromEnv();
  const request = create(CreateProjectFromEnvironmentRequestSchema, {
    name: "<name>",
  });
  const response = await ona.services.project.createProjectFromEnvironment(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.CreateProjectFromEnvironmentRequest{
		Name: "<name>",
	})
	response, err := ona.Services.Project.CreateProjectFromEnvironment(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "name": "<name>"
}

Request

gitpod.v1.CreateProjectFromEnvironmentRequest

Field	Type	Required	Description
`name`	string	No	Constraints: `string.max_len=80, string.min_len=1`.
`environmentId`	string	No	environment_id specifies the environment identifier Constraints: `string.uuid=true`.

Response

gitpod.v1.CreateProjectFromEnvironmentResponse

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

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

Create Project From Environment

Examples

Endpoint

Request example

Request

Response

​Examples

​Endpoint

​Request example

​Request

​Response

​Related types

Examples

Endpoint

Request example

Request

Response

Related types