---
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
  - `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
    - `ports` GitpodV1EnvironmentSpecEnvironmentPort[] — ports controls port sharing
      - `admission` 'ADMISSION_LEVEL_UNSPECIFIED' | 'ADMISSION_LEVEL_OWNER_ONLY' | 'ADMISSION_LEVEL_EVERYONE' — Admission level describes who can access an environment instance and its ports.
      - `name` string — name of this port
      - `port` integer — port number
    - `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

- **2025-02-21** `3655d5ad0ac3` — 2 breaking, 2 warning, 6 info
  - the `metadata` request property type/format changed from ``/`` to `object`/``
  - the `spec` request property type/format changed from ``/`` to `object`/``
  - removed `#/components/schemas/gitpod.v1.UpdateEnvironmentRequest.Metadata` from the `metadata` request property `allOf` list
  - removed `#/components/schemas/gitpod.v1.UpdateEnvironmentRequest.Spec` from the `spec` request property `allOf` list
  - …6 more
- **2025-02-18** `cd6a05ae99d2` — 1 warning
  - removed the optional property `detail` from the response with the `default` status

[Change 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/3655d5ad0ac3/schema)