> ## 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.
# Update Projects
> Updates multiple projects in a single request.
`Unary` ยท [`Projects`](/docs/api-reference/generated/project/overview)
Updates multiple projects in a single request.
Use this method to:
* Modify settings across multiple projects at once
* Apply configuration changes in batch
Returns successfully updated projects and details about any failures.
Each project in the request is processed independently - partial success
is possible.
### Examples
* Update multiple projects:
Updates several projects in one request.
```yaml theme={null}
projects:
- projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "Updated Frontend"
- projectId: "c1f23g7d-5d78-430e-b5b7-e0949c6eb158"
name: "Updated Backend"
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.ProjectService/UpdateProjects
```
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/UpdateProjects" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"projects": [
{
"projectId": ""
}
]
}'
```
```python Python theme={null}
import gitpod.v1.project_pb2 as project_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = project_pb2.UpdateProjectsRequest(
projects=[project_pb2.UpdateProjectRequest(
project_id="",
)],
)
response = ona.services.project.update_projects(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpdateProjectsRequestSchema } from "@gitpod/sdk/gitpod/v1/project_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(UpdateProjectsRequestSchema, {
projects: [{
projectId: "",
}],
});
const response = await ona.services.project.updateProjects(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.UpdateProjectsRequest{
Projects: []*gitpodpb.UpdateProjectRequest{&gitpodpb.UpdateProjectRequest{
ProjectId: "",
}},
})
response, err := ona.Services.Project.UpdateProjects(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"projects": [
{
"projectId": ""
}
]
}
```
## Request
`gitpod.v1.UpdateProjectsRequest`
| Field | Type | Required | Description |
| ---------- | ----------------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
| `projects` | array of [UpdateProjectRequest](#type-gitpod-v1-update-project-request) | No | Constraints: `repeated.max_items=100, repeated.min_items=1`. |
## Response
`gitpod.v1.UpdateProjectsResponse`
| Field | Type | Required | Description |
| ----------------- | -------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
| `updatedProjects` | array of [Project](#type-gitpod-v1-project) | No | updated\_projects contains the successfully updated projects |
| `failedProjects` | array of [Failure](#type-gitpod-v1-update-projects-response-failure) | No | failed\_projects contains details about projects that failed to update |
## Related types
EnvironmentInitializer specifies how an environment is to be initialized
`gitpod.v1.EnvironmentInitializer`
| Field | Type | Required | Description |
| ------- | ------------- | -------- | ----------- |
| `specs` | array of Spec | No | |
`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 | 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 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.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](#type-gitpod-v1-environment-initializer) | 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](#type-gitpod-v1-project-prebuild-configuration) | 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](#type-gitpod-v1-recommended-editors) | 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. |
`gitpod.v1.UpdateProjectsResponse.Failure`
| Field | Type | Required | Description |
| ----------- | ------- | -------- | ---------------------------------------------------- |
| `index` | integer | No | index is the position in the request array (0-based) |
| `projectId` | string | No | project\_id is the project ID that failed |
| `error` | string | No | error describes why the project update failed |
| 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 |