> ## 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 Environment

> Updates an environment's configuration while it is running.

`Unary` · [`Environments`](https://ona.com/docs/api-reference/generated/environment/overview)

Updates an environment's configuration while it is running.

Updates are limited to:

* Git credentials (username, email)
* SSH public keys
* Content initialization
* Port configurations
* Automation files
* Environment timeouts

### Examples

* Update Git credentials:

  Updates the Git configuration for the environment.

  ```yaml theme={null}
  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  spec:
    content:
      gitUsername: "example-user"
      gitEmail: "user@example.com"
  ```

* Add SSH public key:

  Adds a new SSH public key for authentication.

  ```yaml theme={null}
  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  spec:
    sshPublicKeys:
      - id: "0194b7c1-c954-718d-91a4-9a742aa5fc11"
        value: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
  ```

* Update content session:

  Updates the content session identifier for the environment.

  ```yaml theme={null}
  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  spec:
    content:
      session: "0194b7c1-c954-718d-91a4-9a742aa5fc11"
  ```

Note: Machine class changes require stopping the environment and creating a new one.

## Endpoint

```text theme={null}
POST /api/gitpod.v1.EnvironmentService/UpdateEnvironment
```

Send a Bearer token as described in [Authentication](https://ona.com/docs/api-reference.md#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=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.EnvironmentService/UpdateEnvironment" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "environmentId": "<environment-id>"
}'
```

```python Python theme={null}
import gitpod.v1.environment_pb2 as environment_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = environment_pb2.UpdateEnvironmentRequest(
    environment_id="<environment-id>",
)
response = ona.services.environment.update_environment(request)
print(response)
```

```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpdateEnvironmentRequestSchema } from "@gitpod/sdk/gitpod/v1/environment_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(UpdateEnvironmentRequestSchema, {
    environmentId: "<environment-id>",
  });
  const response = await ona.services.environment.updateEnvironment(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.UpdateEnvironmentRequest{
		EnvironmentId: "<environment-id>",
	})
	response, err := ona.Services.Environment.UpdateEnvironment(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}
```

```json Request body theme={null}
{
  "environmentId": "<environment-id>"
}
```

## Request

`gitpod.v1.UpdateEnvironmentRequest`

| Field | Type | Required | Description |
| - | - | - | - |
| `environmentId` | string | No | environment\_id specifies which environment should be updated. Constraints: `string.uuid=true`. |
| `metadata` | [Metadata](#type-gitpod-v1-update-environment-request-metadata) | No | |
| `spec` | [Spec](#type-gitpod-v1-update-environment-request-spec) | No | |

## Response

`gitpod.v1.UpdateEnvironmentResponse`

This message has no fields.

## Related types

> [accordion] EnvironmentPort
>
> `gitpod.v1.EnvironmentSpec.EnvironmentPort`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `port` | integer | No | port number Constraints: `int32.gte=1024, int32.lte=65535`. |
> | `admission` | [AdmissionLevel](#enum-gitpod-v1-admission-level) | No | policy of this port |
> | `name` | string | No | name of this port Constraints: `string.max_len=100, string.min_len=1`. |
> | `protocol` | [Protocol](#enum-gitpod-v1-environment-spec-environment-port-protocol) | No | protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. |
> | `authNonce` | 64-bit integer string | No | auth\_nonce is a monotonically increasing counter incremented by the backend whenever the port's admission level changes. Used by the proxy to invalidate browser auth cookies without requiring a backend round-trip. |

> [accordion] KernelControlsConfig
>
> KernelControlsConfig configures kernel-level controls for the environment
>
> `gitpod.v1.KernelControlsConfig`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `veto` | Veto | No | veto controls blocking mechanisms |
> | `bpfDebugLevel` | [BPFDebugLevel](#enum-gitpod-v1-bpf-debug-level) | No | bpf\_debug\_level controls the verbosity of BPF trace\_pipe output for all BPF-based agents in this environment. |

> [accordion] AutomationsFile
>
> `gitpod.v1.UpdateEnvironmentRequest.AutomationsFile`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `session` | string | No | |
> | `automationsFilePath` | string | No | automations\_file\_path is the path to the automations file that is applied in the environment, relative to the repo root. Constraints: `cel.expression=this.matches('^$\|^[^/].*'), cel.id=relative_path, cel.message=path must not be absolute (start with a /)`. |

> [accordion] Content
>
> `gitpod.v1.UpdateEnvironmentRequest.Content`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `session` | string | No | session should be changed to trigger a content reinitialization |
> | `initializer` | EnvironmentInitializer | No | initializer configures how the environment is to be initialized |
> | `gitUsername` | string | No | The Git username |
> | `gitEmail` | string | No | The Git email address |

> [accordion] DevContainer
>
> `gitpod.v1.UpdateEnvironmentRequest.DevContainer`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `session` | string | No | session should be changed to trigger a devcontainer rebuild |
> | `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 /)`. |

> [accordion] Metadata
>
> `gitpod.v1.UpdateEnvironmentRequest.Metadata`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `name` | string | No | name is the user-defined display name of the environment Constraints: `string.max_len=128`. |
> | `lockdownAt` | RFC 3339 timestamp | No | lockdown\_at sets or clears the lockdown time for this environment. Only org admins can set this field. When set to a future time, the environment will become blocked at that time. When cleared (set to epoch zero), the lockdown is removed. Setting to a past time is rejected. |

> [accordion] SSHPublicKey
>
> `gitpod.v1.UpdateEnvironmentRequest.SSHPublicKey`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | No | id is the unique identifier of the public key |
> | `value` | string | No | value is the actual public key in the public key file format if not provided, the public key will be removed |

> [accordion] Spec
>
> `gitpod.v1.UpdateEnvironmentRequest.Spec`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `content` | [Content](#type-gitpod-v1-update-environment-request-content) | No | |
> | `sshPublicKeys` | array of [SSHPublicKey](#type-gitpod-v1-update-environment-request-ssh-public-key) | No | ssh\_public\_keys are the public keys to update empty array means nothing to update |
> | `devcontainer` | [DevContainer](#type-gitpod-v1-update-environment-request-dev-container) | No | |
> | `ports` | array of [EnvironmentPort](#type-gitpod-v1-environment-spec-environment-port) | No | ports controls port sharing |
> | `timeout` | [Timeout](#type-gitpod-v1-update-environment-request-timeout) | No | Timeout configures the environment timeout |
> | `automationsFile` | [AutomationsFile](#type-gitpod-v1-update-environment-request-automations-file) | No | automations\_file is the automations file spec of the environment |
> | `kernelControlsConfig` | [KernelControlsConfig](#type-gitpod-v1-kernel-controls-config) | No | kernel\_controls\_config configures kernel-level controls for this environment |

> [accordion] Timeout
>
> `gitpod.v1.UpdateEnvironmentRequest.Timeout`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `disconnected` | duration string | No | inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. Constraints: `cel.expression=this == duration('0s') \|\| this >= duration('1800s'), cel.id=disconnected_timeout, cel.message=value must be 0s (disabled) or at least 1800s (30 minutes)`. |

> [accordion] AdmissionLevel
>
> Admission level describes who can access an environment instance and its ports.
>
> | Value | Number | Description |
> | - | -: | - |
> | `ADMISSION_LEVEL_UNSPECIFIED` | 0 | |
> | `ADMISSION_LEVEL_OWNER_ONLY` | 1 | **Deprecated.** ADMISSION\_LEVEL\_OWNER\_ONLY means the environment can only be accessed by the creator. Deprecated: Use ADMISSION\_LEVEL\_CREATOR\_ONLY instead. |
> | `ADMISSION_LEVEL_EVERYONE` | 2 | ADMISSION\_LEVEL\_EVERYONE means the environment (including ports) can be accessed by everyone. |
> | `ADMISSION_LEVEL_ORGANIZATION` | 3 | ADMISSION\_LEVEL\_ORGANIZATION means the environment (including ports) can be accessed by all members of the organization. |
> | `ADMISSION_LEVEL_CREATOR_ONLY` | 4 | ADMISSION\_LEVEL\_CREATOR\_ONLY means the environment (including ports) can only be accessed by the user who created the environment. |

> [accordion] BPFDebugLevel
>
> BPFDebugLevel controls the verbosity of BPF trace\_pipe output (bpf\_printk).
> Applies to all BPF-based agents (veto exec, future agents).
>
> | Value | Number | Description |
> | - | -: | - |
> | `BPF_DEBUG_LEVEL_UNSPECIFIED` | 0 | BPF\_DEBUG\_LEVEL\_UNSPECIFIED disables all bpf\_printk output (default). |
> | `BPF_DEBUG_LEVEL_INFO` | 1 | BPF\_DEBUG\_LEVEL\_INFO enables decision-level prints (e.g., veto allow/block). |
> | `BPF_DEBUG_LEVEL_VERBOSE` | 2 | BPF\_DEBUG\_LEVEL\_VERBOSE enables all debug prints including data fillers. |

> [accordion] Protocol
>
> Protocol describes the communication protocol between Gateway and user environment services.
>
> | Value | Number | Description |
> | - | -: | - |
> | `PROTOCOL_UNSPECIFIED` | 0 | |
> | `PROTOCOL_HTTP` | 1 | |
> | `PROTOCOL_HTTPS` | 2 | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.