--- title: "UpdateEnvironment" method: POST path: "/gitpod.v1.EnvironmentService/UpdateEnvironment" tags: ["gitpod.v1.EnvironmentService"] --- # UpdateEnvironment `POST /gitpod.v1.EnvironmentService/UpdateEnvironment` 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 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 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 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. ## Request body - GitpodV1UpdateEnvironmentRequest - `environmentId` string, uuid — environment_id specifies which environment should be updated. +required - `metadata` GitpodV1UpdateEnvironmentRequestMetadata - `lockdownAt` string, date-time — A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format. - `name` string, nullable — name is the user-defined display name of the environment - `pinnedByCreator` boolean, nullable — pinned_by_creator sets whether the environment is pinned in navigation surfaces. - `spec` GitpodV1UpdateEnvironmentRequestSpec - `automationsFile` GitpodV1UpdateEnvironmentRequestAutomationsFile - `automationsFilePath` string, nullable — automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session` string, nullable - `content` GitpodV1UpdateEnvironmentRequestContent - `gitEmail` string, nullable — The Git email address - `gitUsername` string, nullable — The Git username - `initializer` GitpodV1EnvironmentInitializer — unresolved $ref - `session` string, nullable — session should be changed to trigger a content reinitialization - `devcontainer` GitpodV1UpdateEnvironmentRequestDevContainer - `devcontainerFilePath` string, nullable — devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session` string, nullable — session should be changed to trigger a devcontainer rebuild - `kernelControlsConfig` GitpodV1KernelControlsConfig — KernelControlsConfig configures kernel-level controls for the environment - `bpfDebugLevel` 'BPF_DEBUG_LEVEL_UNSPECIFIED' | 'BPF_DEBUG_LEVEL_INFO' | 'BPF_DEBUG_LEVEL_VERBOSE' — BPFDebugLevel controls the verbosity of BPF trace_pipe output (bpf_printk). Applies to all BPF-based agents (veto exec, future agents). - `veto` GitpodV1Veto — Veto controls kernel-level blocking mechanisms - `exec` GitpodV1VetoExec — Exec controls executable blocking - `action` 'KERNEL_CONTROLS_ACTION_UNSPECIFIED' | 'KERNEL_CONTROLS_ACTION_BLOCK' | 'KERNEL_CONTROLS_ACTION_AUDIT' — KernelControlsAction defines how a kernel-level policy violation is handled. - `denyBlockDevices` boolean — deny_block_devices blocks opening of block devices (S_ISBLK) system-wide inside the environment. Deprecated: use veto.file.block_devices instead. - `denylist` string[] — denylist is the list of executable paths or names to block - `enabled` boolean — enabled controls whether executable blocking is active - `resolveBareNames` boolean — resolve_bare_names enables the discovery agent to resolve bare executable names in the denylist to full filesystem paths. Gated by a feature flag for incremental rollout. - `untouchable` boolean — untouchable enables file I/O blocking on denylisted files. When true, every read()/write() on a denylisted file is blocked via the security_file_permission LSM hook. Gated by a feature flag. - `watch` boolean — watch enables the BPF file watcher that emits events when denylisted files are modified, unlinked, or renamed. Used by the self-healing responder to keep the hash denylist up to date. - `file` GitpodV1VetoFile — File controls file-level access mechanisms. - `blockDevices` GitpodV1VetoFileBlockDevicesPolicy — VetoFileBlockDevicesPolicy defines block-device open control. - `action` 'KERNEL_CONTROLS_ACTION_UNSPECIFIED' | 'KERNEL_CONTROLS_ACTION_BLOCK' | 'KERNEL_CONTROLS_ACTION_AUDIT' — KernelControlsAction defines how a kernel-level policy violation is handled. - `enabled` boolean — enabled controls whether opening block devices is denied or audited. - `enabled` boolean — enabled controls whether file-native policy is active. - `paths` GitpodV1VetoFilePathPolicy — VetoFilePathPolicy defines path-based file-content access control. - `defaultEffect` 'KERNEL_CONTROLS_ACTION_UNSPECIFIED' | 'KERNEL_CONTROLS_ACTION_BLOCK' | 'KERNEL_CONTROLS_ACTION_AUDIT' — KernelControlsAction defines how a kernel-level policy violation is handled. - `defaultSurface` 'VETO_FILE_SURFACE_UNSPECIFIED' | 'VETO_FILE_SURFACE_ACCESS' | 'VETO_FILE_SURFACE_CONTENT_MUTATION' | 'VETO_FILE_SURFACE_CONTENT_READ' — VetoFileSurface defines which file operation classes a path entry targets. - `entries` GitpodV1VetoFilePathEntry[] — entries is the list of per-path file policies. - … - `supervisorProtection` GitpodV1VetoFileSupervisorProtection — SupervisorProtection controls internal protection for the supervisor binary. This is materialized by the backend from supervisor_self_protection_mode and is not customer policy. - `effect` 'KERNEL_CONTROLS_ACTION_UNSPECIFIED' | 'KERNEL_CONTROLS_ACTION_BLOCK' | 'KERNEL_CONTROLS_ACTION_AUDIT' — KernelControlsAction defines how a kernel-level policy violation is handled. - `enabled` boolean, nullable — enabled controls whether the supervisor binary internal source is active. - `ports` GitpodV1EnvironmentSpecEnvironmentPort[] — ports controls port sharing - `admission` 'ADMISSION_LEVEL_UNSPECIFIED' | 'ADMISSION_LEVEL_OWNER_ONLY' | 'ADMISSION_LEVEL_EVERYONE' | 'ADMISSION_LEVEL_ORGANIZATION' | 'ADMISSION_LEVEL_CREATOR_ONLY' — Admission level describes who can access an environment instance and its ports. - `authNonce` string — 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. - `name` string — name of this port - `port` integer — port number - `protocol` 'PROTOCOL_UNSPECIFIED' | 'PROTOCOL_HTTP' | 'PROTOCOL_HTTPS' — Protocol describes the communication protocol between Gateway and user environment services. - `sshPublicKeys` GitpodV1UpdateEnvironmentRequestSSHPublicKey[] — ssh_public_keys are the public keys to update empty array means nothing to update - `id` string — id is the unique identifier of the public key - `value` string, nullable — value is the actual public key in the public key file format if not provided, the public key will be removed - `timeout` GitpodV1UpdateEnvironmentRequestTimeout - `disconnected` string, regex — A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years. # Examples Example 1: Compute Duration from two Timestamps in pseudo code. Timestamp start = ...; Timestamp end = ...; Duration duration = ...; duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos; if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; } Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. Timestamp start = ...; Duration duration = ...; Timestamp end = ...; end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos; if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; } Example 3: Compute Duration from datetime.timedelta in Python. td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td) # JSON Mapping In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s". ## Response `200` Success - GitpodV1UpdateEnvironmentResponse ## Other responses - `default` — Error ## Changes > 18 revisions in range; 1 could not be searched. - **2026-04-02** `dabc0ff98cd7` — 7 info - added the new optional request property `metadata/lockdownAt` - added the new optional request property `spec/kernelControlsConfig/bpfDebugLevel` - added the new optional request property `spec/kernelControlsConfig/veto/exec/denyBlockDevices` - added the new optional request property `spec/kernelControlsConfig/veto/exec/resolveBareNames` - …3 more - **2026-02-18** `1923b5d38655` — 1 info - added the new optional request property `spec/kernelControlsConfig/veto/exec/action` - **2026-02-11** `b97dcde84128` — 3 info - added the new optional request property `spec/kernelControlsConfig` - added the new `ADMISSION_LEVEL_CREATOR_ONLY` enum value to the request property `spec/ports/items/admission` - added the new `ADMISSION_LEVEL_ORGANIZATION` enum value to the request property `spec/ports/items/admission` - **2025-12-15** `d62ef4b9187c` — 1 breaking, 1 warning, 2 info - the `spec/ports/items/port` request property's min was increased to `1024.00` - the `metadata/name` request property's maxLength was set to `128` - added the new optional request property `spec/ports/items/protocol` - added the new `CLONE_TARGET_MODE_REMOTE_TAG` enum value to the request property `spec/content/initializer/specs/items/git/targetMode` - **2025-06-10** `ca9a49ac7fbb` — 1 info - added the new optional request property `metadata/name` [Full history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.EnvironmentService/UpdateEnvironment/post.md) --- [API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/44d50c2ac284/schema)