Update Project

Unary · Projects Updates a project’s configuration. Use this method to:

Modify project settings
Update environment class
Change project name
Configure initializers
Configure prebuild settings

Examples

Update project name: Changes the project’s display name.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "New Project Name"

Enable prebuilds with daily schedule: Configures prebuilds to run daily at 2 AM UTC.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
prebuildConfiguration:
  enabled: true
  environmentClassIds:
    - "b0e12f6c-4c67-429d-a4a6-d9838b5da041"
  timeout: "3600s"
  trigger:
    dailySchedule:
      hourUtc: 2

Endpoint

POST /api/gitpod.v1.ProjectService/UpdateProject

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

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

ona = create_client_from_env()
request = project_pb2.UpdateProjectRequest(
    project_id="<project-id>",
)
response = ona.services.project.update_project(request)
print(response)

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

async function main() {
  const ona = createClientFromEnv();
  const request = create(UpdateProjectRequestSchema, {
    projectId: "<project-id>",
  });
  const response = await ona.services.project.updateProject(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.UpdateProjectRequest{
		ProjectId: "<project-id>",
	})
	response, err := ona.Services.Project.UpdateProject(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "projectId": "<project-id>"
}

Request

gitpod.v1.UpdateProjectRequest

Field	Type	Required	Description
`projectId`	string	No	project_id specifies the project identifier Constraints: `string.uuid=true`.
`name`	string	No	Constraints: `string.max_len=80, string.min_len=1`.
`initializer`	EnvironmentInitializer	No	initializer is the content initializer
`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 provided, the existing prebuild configuration is not modified. To disable prebuilds, set enabled to false.
`recommendedEditors`	RecommendedEditors	No	recommended_editors specifies the editors recommended for this project. If not provided, the existing recommended editors are not modified. To clear all recommended editors, set to an empty RecommendedEditors message.

Response

gitpod.v1.UpdateProjectResponse

Field	Type	Required	Description
`project`	Project	No

EditorVersions

EditorVersions contains the recommended versions for an editor.gitpod.v1.EditorVersions

Field	Type	Required	Description
`versions`	array of string	No	versions is the list of recommended versions for this editor. If empty, all available versions are recommended. Examples for JetBrains: [“2025.1”, “2024.3”]

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