UpdateEnvironment

environments.update() -> object

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

environment_id: Optional[str]

environment_id specifies which environment should be updated.

+required

formatuuid

metadata: Optional[Metadata]

name: Optional[str]

name is the user-defined display name of the environment

maxLength128

spec: Optional[Spec]

automations_file: Optional[SpecAutomationsFile]

automations_file is the automations file spec of the environment

automations_file_path: Optional[str]

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[str]

content: Optional[SpecContent]

git_email: Optional[str]

The Git email address

git_username: Optional[str]

The Git username

initializer: Optional[EnvironmentInitializerParam]

initializer configures how the environment is to be initialized

specs: Optional[List[Spec]]

context_url: Optional[SpecContextURL]

url: Optional[str]

url is the URL from which the environment is created

formaturi

git: Optional[SpecGit]

checkout_location: Optional[str]

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

clone_target: Optional[str]

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

remote_uri: Optional[str]

remote_uri is the Git remote origin

target_mode: Optional[Literal["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"

upstream_remote_uri: Optional[str]

upstream_Remote_uri is the fork upstream of a repository

session: Optional[str]

session should be changed to trigger a content reinitialization

devcontainer: Optional[SpecDevcontainer]

devcontainer_file_path: Optional[str]

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[str]

session should be changed to trigger a devcontainer rebuild

kernel_controls_config: Optional[KernelControlsConfigParam]

kernel_controls_config configures kernel-level controls for this environment

veto: Optional[Veto]

veto controls blocking mechanisms

exec: Optional[Exec]

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[List[str]]

denylist is the list of executable paths or names to block

enabled: Optional[bool]

enabled controls whether executable blocking is active

ports: Optional[Iterable[SpecPort]]

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[str]

name of this port

maxLength100

minLength1

port: Optional[int]

port number

formatint32

maximum65535

minimum1024

protocol: Optional[Literal["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"

ssh_public_keys: Optional[Iterable[SpecSSHPublicKey]]

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

id: Optional[str]

id is the unique identifier of the public key

value: Optional[str]

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

timeout: Optional[SpecTimeout]

Timeout configures the environment timeout

disconnected: Optional[str]

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

object

UpdateEnvironment

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
environment = client.environments.update(
    environment_id="07e03a28-65a5-4d98-b532-8ea67b188048",
    spec={
        "ssh_public_keys": [{
            "id": "0194b7c1-c954-718d-91a4-9a742aa5fc11",
            "value": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...",
        }]
    },
)
print(environment)

{}

Returns Examples

{}