Update Environment

Unary · Environments 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.

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.

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.

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

POST /api/gitpod.v1.EnvironmentService/UpdateEnvironment

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.EnvironmentService/UpdateEnvironment" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "environmentId": "<environment-id>"
}'

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)

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);

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)
}

{
  "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	No
`spec`	Spec	No

Response

gitpod.v1.UpdateEnvironmentResponse This message has no fields.

EnvironmentPort

gitpod.v1.EnvironmentSpec.EnvironmentPort

Field	Type	Required	Description
`port`	integer	No	port number Constraints: `int32.gte=1024, int32.lte=65535`.
`admission`	AdmissionLevel	No	policy of this port
`name`	string	No	name of this port Constraints: `string.max_len=100, string.min_len=1`.
`protocol`	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

KernelControlsConfig configures kernel-level controls for the environmentgitpod.v1.KernelControlsConfig

Field	Type	Required	Description
`veto`	Veto	No	veto controls blocking mechanisms
`bpfDebugLevel`	BPFDebugLevel	No	bpf_debug_level controls the verbosity of BPF trace_pipe output for all BPF-based agents in this environment.

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 /)`.

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

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 /)`.

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.

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

Spec

gitpod.v1.UpdateEnvironmentRequest.Spec

Field	Type	Required	Description
`content`	Content	No
`sshPublicKeys`	array of SSHPublicKey	No	ssh_public_keys are the public keys to update empty array means nothing to update
`devcontainer`	DevContainer	No
`ports`	array of EnvironmentPort	No	ports controls port sharing
`timeout`	Timeout	No	Timeout configures the environment timeout
`automationsFile`	AutomationsFile	No	automations_file is the automations file spec of the environment
`kernelControlsConfig`	KernelControlsConfig	No	kernel_controls_config configures kernel-level controls for this environment

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)`.

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.

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.

Protocol

Protocol describes the communication protocol between Gateway and user environment services.

Value	Number	Description
`PROTOCOL_UNSPECIFIED`	0
`PROTOCOL_HTTP`	1
`PROTOCOL_HTTPS`	2

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