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.

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.

Body ParametersJSONExpand Collapse

environmentId: optional string

environment_id specifies which environment should be updated.

+required

formatuuid

metadata: optional object { name }

name: optional string

name is the user-defined display name of the environment

maxLength128

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 { specs }

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

formaturi

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

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: 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 { veto }

kernel_controls_config configures kernel-level controls for this environment

veto: optional Veto { exec }

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

One of the following:

"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

One of the following:

"ADMISSION_LEVEL_UNSPECIFIED"

"ADMISSION_LEVEL_OWNER_ONLY"

"ADMISSION_LEVEL_EVERYONE"

"ADMISSION_LEVEL_ORGANIZATION"

"ADMISSION_LEVEL_CREATOR_ONLY"

name: optional string

name of this port

maxLength100

minLength1

port: optional number

port number

formatint32

maximum65535

minimum1024

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.

One of the following:

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

formatregex

UpdateEnvironment

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

{}

Returns Examples

{}