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

### Body Parameters

- `environmentId: optional string`

  environment_id specifies which environment should be updated.

  +required

- `metadata: optional object { name }`

  - `name: optional string`

    name is the user-defined display name of the environment

- `spec: optional object { automationsFile, content, devcontainer, 4 more }`

  - `automationsFile: optional object { automationsFilePath, session }`

    automations_file is the automations file spec of the environment

    - `automationsFilePath: optional string`

      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: optional string`

  - `content: optional object { gitEmail, gitUsername, initializer, session }`

    - `gitEmail: optional string`

      The Git email address

    - `gitUsername: optional string`

      The Git username

    - `initializer: optional EnvironmentInitializer`

      initializer configures how the environment is to be initialized

      - `specs: optional array of object { contextUrl, git }`

        - `contextUrl: optional object { url }`

          - `url: optional string`

            url is the URL from which the environment is created

        - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }`

          - `checkoutLocation: optional string`

            a path relative to the environment root in which the code will be checked out
            to

          - `cloneTarget: optional string`

            the value for the clone target mode - use depends on the target mode

          - `remoteUri: optional string`

            remote_uri is the Git remote origin

          - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more`

            the target mode determines what gets checked out

            - `"CLONE_TARGET_MODE_UNSPECIFIED"`

            - `"CLONE_TARGET_MODE_REMOTE_HEAD"`

            - `"CLONE_TARGET_MODE_REMOTE_COMMIT"`

            - `"CLONE_TARGET_MODE_REMOTE_BRANCH"`

            - `"CLONE_TARGET_MODE_LOCAL_BRANCH"`

            - `"CLONE_TARGET_MODE_REMOTE_TAG"`

          - `upstreamRemoteUri: optional string`

            upstream_Remote_uri is the fork upstream of a repository

    - `session: optional string`

      session should be changed to trigger a content reinitialization

  - `devcontainer: optional object { devcontainerFilePath, session }`

    - `devcontainerFilePath: optional string`

      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: optional string`

      session should be changed to trigger a devcontainer rebuild

  - `kernelControlsConfig: optional KernelControlsConfig`

    kernel_controls_config configures kernel-level controls for this environment

    - `veto: optional Veto`

      veto controls blocking mechanisms

      - `exec: optional object { action, denylist, enabled }`

        exec controls executable blocking

        - `action: optional KernelControlsAction`

          action specifies what action kernel-level controls take on policy violations

          - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"`

          - `"KERNEL_CONTROLS_ACTION_BLOCK"`

          - `"KERNEL_CONTROLS_ACTION_AUDIT"`

        - `denylist: optional array of string`

          denylist is the list of executable paths or names to block

        - `enabled: optional boolean`

          enabled controls whether executable blocking is active

  - `ports: optional array of object { admission, name, port, protocol }`

    ports controls port sharing

    - `admission: optional AdmissionLevel`

      policy of this port

      - `"ADMISSION_LEVEL_UNSPECIFIED"`

      - `"ADMISSION_LEVEL_OWNER_ONLY"`

      - `"ADMISSION_LEVEL_EVERYONE"`

      - `"ADMISSION_LEVEL_ORGANIZATION"`

      - `"ADMISSION_LEVEL_CREATOR_ONLY"`

    - `name: optional string`

      name of this port

    - `port: optional number`

      port number

    - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"`

      protocol for communication (Gateway proxy → user environment service).
      this setting only affects the protocol used between Gateway and user environment services.

      - `"PROTOCOL_UNSPECIFIED"`

      - `"PROTOCOL_HTTP"`

      - `"PROTOCOL_HTTPS"`

  - `sshPublicKeys: optional array of object { id, value }`

    ssh_public_keys are the public keys to update
    empty array means nothing to update

    - `id: optional string`

      id is the unique identifier of the public key

    - `value: optional string`

      value is the actual public key in the public key file format
      if not provided, the public key will be removed

  - `timeout: optional object { disconnected }`

    Timeout configures the environment timeout

    - `disconnected: optional string`

      inacitivity is the maximum time of disconnection before the environment is
      stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable.
      value must be 0s (disabled) or at least 1800s (30 minutes):

      ```
      this == duration('0s') || this >= duration('1800s')
      ```

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/UpdateEnvironment \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

#### Response

```json
{}
```