UpdateEnvironment

client.environments.update(, ?): EnvironmentUpdateResponse

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.

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.

ParametersExpand Collapse

body: EnvironmentUpdateParams { environmentId, metadata, spec }

environmentId?: string

environment_id specifies which environment should be updated.

+required

formatuuid

metadata?: Metadata | null

name?: string | null

name is the user-defined display name of the environment

maxLength128

spec?: Spec | null

automationsFile?: AutomationsFile | null

automations_file is the automations file spec of the environment

automationsFilePath?: string | null

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 | null

content?: Content | null

gitEmail?: string | null

The Git email address

gitUsername?: string | null

The Git username

initializer?: EnvironmentInitializer { specs } | null

initializer configures how the environment is to be initialized

specs?: Array<Spec>

contextUrl?: ContextURL { url }

url?: string

url is the URL from which the environment is created

formaturi

git?: Git { checkoutLocation, cloneTarget, remoteUri, 2 more }

checkoutLocation?: string

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

cloneTarget?: string

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

remoteUri?: string

remote_uri is the Git remote origin

targetMode?: "CLONE_TARGET_MODE_UNSPECIFIED" | "CLONE_TARGET_MODE_REMOTE_HEAD" | "CLONE_TARGET_MODE_REMOTE_COMMIT" | 3 more

the target mode determines what gets checked out

One of the following:

"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?: string

upstream_Remote_uri is the fork upstream of a repository

session?: string | null

session should be changed to trigger a content reinitialization

devcontainer?: Devcontainer | null

devcontainerFilePath?: string | null

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 | null

session should be changed to trigger a devcontainer rebuild

kernelControlsConfig?: KernelControlsConfig { veto } | null

kernel_controls_config configures kernel-level controls for this environment

veto?: Veto { exec }

veto controls blocking mechanisms

exec?: Exec { action, denylist, enabled }

exec controls executable blocking

action?: KernelControlsAction

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

One of the following:

"KERNEL_CONTROLS_ACTION_UNSPECIFIED"

"KERNEL_CONTROLS_ACTION_BLOCK"

"KERNEL_CONTROLS_ACTION_AUDIT"

denylist?: Array<string>

denylist is the list of executable paths or names to block

enabled?: boolean

enabled controls whether executable blocking is active

ports?: Array<Port>

ports controls port sharing

admission?: AdmissionLevel

policy of this port

One of the following:

"ADMISSION_LEVEL_UNSPECIFIED"

"ADMISSION_LEVEL_OWNER_ONLY"

"ADMISSION_LEVEL_EVERYONE"

"ADMISSION_LEVEL_ORGANIZATION"

"ADMISSION_LEVEL_CREATOR_ONLY"

name?: string

name of this port

maxLength100

minLength1

port?: number

port number

formatint32

maximum65535

minimum1024

protocol?: "PROTOCOL_UNSPECIFIED" | "PROTOCOL_HTTP" | "PROTOCOL_HTTPS"

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

One of the following:

"PROTOCOL_UNSPECIFIED"

"PROTOCOL_HTTP"

"PROTOCOL_HTTPS"

sshPublicKeys?: Array<SSHPublicKey>

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 | null

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

timeout?: Timeout | null

Timeout configures the environment timeout

disconnected?: string | null

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

formatregex

ReturnsExpand Collapse

EnvironmentUpdateResponse = unknown

UpdateEnvironment

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

const environment = await client.environments.update({
  environmentId: '07e03a28-65a5-4d98-b532-8ea67b188048',
  spec: {
    sshPublicKeys: [
      {
        id: '0194b7c1-c954-718d-91a4-9a742aa5fc11',
        value: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...',
      },
    ],
  },
});

console.log(environment);

{}

Returns Examples

{}