> ## 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`](/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](/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.EnvironmentService/UpdateEnvironment" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"environmentId": ""
}'
```
```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="",
)
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: "",
});
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: "",
})
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": ""
}
```
## 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
`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. |
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. |
`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 /)`. |
`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 |
`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 /)`. |
`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. |
`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 |
`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 |
`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)`. |
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. |
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. |
Protocol describes the communication protocol between Gateway and user environment services.
| Value | Number | Description |
| ---------------------- | -----: | ----------- |
| `PROTOCOL_UNSPECIFIED` | 0 | |
| `PROTOCOL_HTTP` | 1 | |
| `PROTOCOL_HTTPS` | 2 | |