Environments
CreateEnvironment
CreateEnvironmentAccessToken
CreateEnvironmentFromProject
CreateEnvironmentLogsToken
DeleteEnvironment
ListEnvironments
MarkEnvironmentActive
GetEnvironment
StartEnvironment
StopEnvironment
UnarchiveEnvironment
UpdateEnvironment
ModelsExpand Collapse
Environment { id, metadata, spec, status } +resource get environment
+resource get environment
ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager
Metadata is data associated with this environment that’s required for other
parts of Gitpod to function
Metadata is data associated with this environment that’s required for other parts of Gitpod to function
annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented
Time when the Environment was archived. If not set, the environment is not archived.
Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called).
lockdown_at is the time at which the environment becomes locked down due to the organization’s maximum environment lifetime policy. Nil when no lifetime policy applies.
organization_id is the ID of the organization that contains the environment
original_context_url is the normalized URL from which the environment was created
prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild.
If the Environment was started from a project, the project_id will reference the project.
Spec is the configuration of the environment that’s required for the
runner to start the environment
Spec is the configuration of the environment that’s required for the runner to start the environment
automationsFile?: AutomationsFile { automationsFilePath, session, triggerFilter } automations_file is the automations file spec of the environment
automations_file is the automations file spec of the environment
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('^$|^[^/].*')content?: Content { gitEmail, gitUsername, initializer, session } content is the content spec of the environment
content is the content spec of the environment
initializer configures how the environment is to be initialized
initializer configures how the environment is to be initialized
specs?: Array<Spec>
git?: Git { checkoutLocation, cloneTarget, remoteUri, 2 more }
devcontainer?: Devcontainer { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more } devcontainer is the devcontainer spec of the environment
devcontainer is the devcontainer spec of the environment
default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found
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('^$|^[^/].*')dotfiles?: Dotfiles { repository } Experimental: dotfiles is the dotfiles configuration of the devcontainer
Experimental: dotfiles is the dotfiles configuration of the devcontainer
URL of a dotfiles Git repository (e.g. https://github.com/owner/repository)
kernel_controls_config configures kernel-level controls for this environment
kernel_controls_config configures kernel-level controls for this environment
ports?: Array<Port>ports is the set of ports which ought to be exposed to your network
ports is the set of ports which ought to be exposed to your network
secrets?: Array<Secret>secrets are confidential data that is mounted into the environment
secrets are confidential data that is mounted into the environment
api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.
container_registry_basic_auth_host is the hostname of the container registry that supports basic auth
credentialProxy?: CredentialProxy { format, header, targetHosts } credential_proxy configures transparent credential injection via the
credential proxy. When set, the credential proxy intercepts HTTPS
traffic to the target hosts and replaces the dummy secret value with
the real value in the specified HTTP header. The real secret value is
never exposed in the environment.
This field is orthogonal to mount — a secret can be both mounted (e.g.
as a git credential) and proxied at the same time.
credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time.
scope?: "SCOPE_UNSPECIFIED" | "SCOPE_ORGANIZATION" | "SCOPE_PROJECT" | 3 morescope indicates where this secret originated from.
Used to filter secrets during build (only org and project secrets are injected).
scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).
version of the spec. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b.
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys are the public keys used to ssh into the environment
ssh_public_keys are the public keys used to ssh into the environment
Status is the current status of the environment
Status is the current status of the environment
activity_signal is the last activity signal for the environment.
activity_signal is the last activity signal for the environment.
automationsFile?: AutomationsFile { automationsFilePath, automationsFilePresence, failureMessage, 3 more } automations_file contains the status of the automations file.
automations_file contains the status of the automations file.
automations_file_path is the path to the automations file relative to the repo root.
automationsFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_ABSENT" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"automations_file_presence indicates how an automations file is present in the environment.
automations_file_presence indicates how an automations file is present in the environment.
failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED.
phase?: "CONTENT_PHASE_UNSPECIFIED" | "CONTENT_PHASE_CREATING" | "CONTENT_PHASE_INITIALIZING" | 4 morephase is the current phase of the automations file.
phase is the current phase of the automations file.
content?: Content { contentLocationInMachine, failureMessage, git, 3 more } content contains the status of the environment content.
content contains the status of the environment content.
content_location_in_machine is the location of the content in the machine
git?: Git { branch, changedFiles, cloneUrl, 4 more } git is the Git working copy status of the environment.
Note: this is a best-effort field and more often than not will not be
present. Its absence does not indicate the absence of a working copy.
git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy.
changedFiles?: Array<ChangedFile>changed_files is an array of changed files in the environment, possibly
truncated
changed_files is an array of changed files in the environment, possibly truncated
devcontainer?: Devcontainer { containerId, containerName, devcontainerconfigInSync, 9 more } devcontainer contains the status of the devcontainer.
devcontainer contains the status of the devcontainer.
container_name is the name of the container that is used to connect to the devcontainer
devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file.
devcontainer_file_path is the path to the devcontainer file relative to the repo root
devcontainerFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_GENERATED" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"devcontainer_file_presence indicates how the devcontainer file is present in the repo.
devcontainer_file_presence indicates how the devcontainer file is present in the repo.
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_RUNNING" | 2 morephase is the current phase of the devcontainer
phase is the current phase of the devcontainer
remote_workspace_folder is the folder that is used to connect to the devcontainer
environmentUrls?: EnvironmentURLs { logs, ops, ports, 2 more } environment_url contains the URL at which the environment can be accessed.
This field is only set if the environment is running.
environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running.
failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state.
machine?: Machine { failureMessage, phase, session, 3 more } machine contains the status of the environment machine
machine contains the status of the environment machine
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_STARTING" | 5 morephase is the current phase of the environment machine
phase is the current phase of the environment machine
timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out.
the phase of an environment is a simple, high-level summary of where the
environment is in its lifecycle
the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle
runnerAck?: RunnerAck { message, specVersion, statusCode } runner_ack contains the acknowledgement from the runner that is has
received the environment spec.
runner_ack contains the acknowledgement from the runner that is has received the environment spec.
secrets?: Array<Secret>secrets contains the status of the environment secrets
secrets contains the status of the environment secrets
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys contains the status of the environment ssh public keys
ssh_public_keys contains the status of the environment ssh public keys
version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
EnvironmentActivitySignal { source, timestamp } EnvironmentActivitySignal used to signal activity for an environment.
EnvironmentActivitySignal used to signal activity for an environment.
EnvironmentMetadata { annotations, archivedAt, createdAt, 10 more } EnvironmentMetadata is data associated with an environment that’s required for
other parts of the system to function
EnvironmentMetadata is data associated with an environment that’s required for other parts of the system to function
annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented
Time when the Environment was archived. If not set, the environment is not archived.
Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called).
lockdown_at is the time at which the environment becomes locked down due to the organization’s maximum environment lifetime policy. Nil when no lifetime policy applies.
organization_id is the ID of the organization that contains the environment
original_context_url is the normalized URL from which the environment was created
prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild.
If the Environment was started from a project, the project_id will reference the project.
EnvironmentSpec { admission, automationsFile, content, 10 more } EnvironmentSpec specifies the configuration of an environment for an environment
start
EnvironmentSpec specifies the configuration of an environment for an environment start
automationsFile?: AutomationsFile { automationsFilePath, session, triggerFilter } automations_file is the automations file spec of the environment
automations_file is the automations file spec of the environment
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('^$|^[^/].*')content?: Content { gitEmail, gitUsername, initializer, session } content is the content spec of the environment
content is the content spec of the environment
initializer configures how the environment is to be initialized
initializer configures how the environment is to be initialized
specs?: Array<Spec>
git?: Git { checkoutLocation, cloneTarget, remoteUri, 2 more }
devcontainer?: Devcontainer { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more } devcontainer is the devcontainer spec of the environment
devcontainer is the devcontainer spec of the environment
default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found
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('^$|^[^/].*')dotfiles?: Dotfiles { repository } Experimental: dotfiles is the dotfiles configuration of the devcontainer
Experimental: dotfiles is the dotfiles configuration of the devcontainer
URL of a dotfiles Git repository (e.g. https://github.com/owner/repository)
kernel_controls_config configures kernel-level controls for this environment
kernel_controls_config configures kernel-level controls for this environment
ports?: Array<Port>ports is the set of ports which ought to be exposed to your network
ports is the set of ports which ought to be exposed to your network
secrets?: Array<Secret>secrets are confidential data that is mounted into the environment
secrets are confidential data that is mounted into the environment
api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.
container_registry_basic_auth_host is the hostname of the container registry that supports basic auth
credentialProxy?: CredentialProxy { format, header, targetHosts } credential_proxy configures transparent credential injection via the
credential proxy. When set, the credential proxy intercepts HTTPS
traffic to the target hosts and replaces the dummy secret value with
the real value in the specified HTTP header. The real secret value is
never exposed in the environment.
This field is orthogonal to mount — a secret can be both mounted (e.g.
as a git credential) and proxied at the same time.
credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time.
scope?: "SCOPE_UNSPECIFIED" | "SCOPE_ORGANIZATION" | "SCOPE_PROJECT" | 3 morescope indicates where this secret originated from.
Used to filter secrets during build (only org and project secrets are injected).
scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).
version of the spec. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b.
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys are the public keys used to ssh into the environment
ssh_public_keys are the public keys used to ssh into the environment
EnvironmentStatus { activitySignal, automationsFile, content, 10 more } EnvironmentStatus describes an environment status
EnvironmentStatus describes an environment status
activity_signal is the last activity signal for the environment.
activity_signal is the last activity signal for the environment.
automationsFile?: AutomationsFile { automationsFilePath, automationsFilePresence, failureMessage, 3 more } automations_file contains the status of the automations file.
automations_file contains the status of the automations file.
automations_file_path is the path to the automations file relative to the repo root.
automationsFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_ABSENT" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"automations_file_presence indicates how an automations file is present in the environment.
automations_file_presence indicates how an automations file is present in the environment.
failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED.
phase?: "CONTENT_PHASE_UNSPECIFIED" | "CONTENT_PHASE_CREATING" | "CONTENT_PHASE_INITIALIZING" | 4 morephase is the current phase of the automations file.
phase is the current phase of the automations file.
content?: Content { contentLocationInMachine, failureMessage, git, 3 more } content contains the status of the environment content.
content contains the status of the environment content.
content_location_in_machine is the location of the content in the machine
git?: Git { branch, changedFiles, cloneUrl, 4 more } git is the Git working copy status of the environment.
Note: this is a best-effort field and more often than not will not be
present. Its absence does not indicate the absence of a working copy.
git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy.
changedFiles?: Array<ChangedFile>changed_files is an array of changed files in the environment, possibly
truncated
changed_files is an array of changed files in the environment, possibly truncated
devcontainer?: Devcontainer { containerId, containerName, devcontainerconfigInSync, 9 more } devcontainer contains the status of the devcontainer.
devcontainer contains the status of the devcontainer.
container_name is the name of the container that is used to connect to the devcontainer
devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file.
devcontainer_file_path is the path to the devcontainer file relative to the repo root
devcontainerFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_GENERATED" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"devcontainer_file_presence indicates how the devcontainer file is present in the repo.
devcontainer_file_presence indicates how the devcontainer file is present in the repo.
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_RUNNING" | 2 morephase is the current phase of the devcontainer
phase is the current phase of the devcontainer
remote_workspace_folder is the folder that is used to connect to the devcontainer
environmentUrls?: EnvironmentURLs { logs, ops, ports, 2 more } environment_url contains the URL at which the environment can be accessed.
This field is only set if the environment is running.
environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running.
failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state.
machine?: Machine { failureMessage, phase, session, 3 more } machine contains the status of the environment machine
machine contains the status of the environment machine
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_STARTING" | 5 morephase is the current phase of the environment machine
phase is the current phase of the environment machine
timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out.
the phase of an environment is a simple, high-level summary of where the
environment is in its lifecycle
the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle
runnerAck?: RunnerAck { message, specVersion, statusCode } runner_ack contains the acknowledgement from the runner that is has
received the environment spec.
runner_ack contains the acknowledgement from the runner that is has received the environment spec.
secrets?: Array<Secret>secrets contains the status of the environment secrets
secrets contains the status of the environment secrets
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys contains the status of the environment ssh public keys
ssh_public_keys contains the status of the environment ssh public keys
version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
EnvironmentCreateResponse { environment }
+resource get environment
+resource get environment
ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager
Metadata is data associated with this environment that’s required for other
parts of Gitpod to function
Metadata is data associated with this environment that’s required for other parts of Gitpod to function
annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented
Time when the Environment was archived. If not set, the environment is not archived.
Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called).
lockdown_at is the time at which the environment becomes locked down due to the organization’s maximum environment lifetime policy. Nil when no lifetime policy applies.
organization_id is the ID of the organization that contains the environment
original_context_url is the normalized URL from which the environment was created
prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild.
If the Environment was started from a project, the project_id will reference the project.
Spec is the configuration of the environment that’s required for the
runner to start the environment
Spec is the configuration of the environment that’s required for the runner to start the environment
automationsFile?: AutomationsFile { automationsFilePath, session, triggerFilter } automations_file is the automations file spec of the environment
automations_file is the automations file spec of the environment
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('^$|^[^/].*')content?: Content { gitEmail, gitUsername, initializer, session } content is the content spec of the environment
content is the content spec of the environment
initializer configures how the environment is to be initialized
initializer configures how the environment is to be initialized
specs?: Array<Spec>
git?: Git { checkoutLocation, cloneTarget, remoteUri, 2 more }
devcontainer?: Devcontainer { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more } devcontainer is the devcontainer spec of the environment
devcontainer is the devcontainer spec of the environment
default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found
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('^$|^[^/].*')dotfiles?: Dotfiles { repository } Experimental: dotfiles is the dotfiles configuration of the devcontainer
Experimental: dotfiles is the dotfiles configuration of the devcontainer
URL of a dotfiles Git repository (e.g. https://github.com/owner/repository)
kernel_controls_config configures kernel-level controls for this environment
kernel_controls_config configures kernel-level controls for this environment
ports?: Array<Port>ports is the set of ports which ought to be exposed to your network
ports is the set of ports which ought to be exposed to your network
secrets?: Array<Secret>secrets are confidential data that is mounted into the environment
secrets are confidential data that is mounted into the environment
api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.
container_registry_basic_auth_host is the hostname of the container registry that supports basic auth
credentialProxy?: CredentialProxy { format, header, targetHosts } credential_proxy configures transparent credential injection via the
credential proxy. When set, the credential proxy intercepts HTTPS
traffic to the target hosts and replaces the dummy secret value with
the real value in the specified HTTP header. The real secret value is
never exposed in the environment.
This field is orthogonal to mount — a secret can be both mounted (e.g.
as a git credential) and proxied at the same time.
credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time.
scope?: "SCOPE_UNSPECIFIED" | "SCOPE_ORGANIZATION" | "SCOPE_PROJECT" | 3 morescope indicates where this secret originated from.
Used to filter secrets during build (only org and project secrets are injected).
scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).
version of the spec. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b.
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys are the public keys used to ssh into the environment
ssh_public_keys are the public keys used to ssh into the environment
Status is the current status of the environment
Status is the current status of the environment
activity_signal is the last activity signal for the environment.
activity_signal is the last activity signal for the environment.
automationsFile?: AutomationsFile { automationsFilePath, automationsFilePresence, failureMessage, 3 more } automations_file contains the status of the automations file.
automations_file contains the status of the automations file.
automations_file_path is the path to the automations file relative to the repo root.
automationsFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_ABSENT" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"automations_file_presence indicates how an automations file is present in the environment.
automations_file_presence indicates how an automations file is present in the environment.
failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED.
phase?: "CONTENT_PHASE_UNSPECIFIED" | "CONTENT_PHASE_CREATING" | "CONTENT_PHASE_INITIALIZING" | 4 morephase is the current phase of the automations file.
phase is the current phase of the automations file.
content?: Content { contentLocationInMachine, failureMessage, git, 3 more } content contains the status of the environment content.
content contains the status of the environment content.
content_location_in_machine is the location of the content in the machine
git?: Git { branch, changedFiles, cloneUrl, 4 more } git is the Git working copy status of the environment.
Note: this is a best-effort field and more often than not will not be
present. Its absence does not indicate the absence of a working copy.
git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy.
changedFiles?: Array<ChangedFile>changed_files is an array of changed files in the environment, possibly
truncated
changed_files is an array of changed files in the environment, possibly truncated
devcontainer?: Devcontainer { containerId, containerName, devcontainerconfigInSync, 9 more } devcontainer contains the status of the devcontainer.
devcontainer contains the status of the devcontainer.
container_name is the name of the container that is used to connect to the devcontainer
devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file.
devcontainer_file_path is the path to the devcontainer file relative to the repo root
devcontainerFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_GENERATED" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"devcontainer_file_presence indicates how the devcontainer file is present in the repo.
devcontainer_file_presence indicates how the devcontainer file is present in the repo.
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_RUNNING" | 2 morephase is the current phase of the devcontainer
phase is the current phase of the devcontainer
remote_workspace_folder is the folder that is used to connect to the devcontainer
environmentUrls?: EnvironmentURLs { logs, ops, ports, 2 more } environment_url contains the URL at which the environment can be accessed.
This field is only set if the environment is running.
environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running.
failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state.
machine?: Machine { failureMessage, phase, session, 3 more } machine contains the status of the environment machine
machine contains the status of the environment machine
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_STARTING" | 5 morephase is the current phase of the environment machine
phase is the current phase of the environment machine
timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out.
the phase of an environment is a simple, high-level summary of where the
environment is in its lifecycle
the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle
runnerAck?: RunnerAck { message, specVersion, statusCode } runner_ack contains the acknowledgement from the runner that is has
received the environment spec.
runner_ack contains the acknowledgement from the runner that is has received the environment spec.
secrets?: Array<Secret>secrets contains the status of the environment secrets
secrets contains the status of the environment secrets
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys contains the status of the environment ssh public keys
ssh_public_keys contains the status of the environment ssh public keys
version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
EnvironmentCreateFromProjectResponse { environment }
+resource get environment
+resource get environment
ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager
Metadata is data associated with this environment that’s required for other
parts of Gitpod to function
Metadata is data associated with this environment that’s required for other parts of Gitpod to function
annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented
Time when the Environment was archived. If not set, the environment is not archived.
Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called).
lockdown_at is the time at which the environment becomes locked down due to the organization’s maximum environment lifetime policy. Nil when no lifetime policy applies.
organization_id is the ID of the organization that contains the environment
original_context_url is the normalized URL from which the environment was created
prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild.
If the Environment was started from a project, the project_id will reference the project.
Spec is the configuration of the environment that’s required for the
runner to start the environment
Spec is the configuration of the environment that’s required for the runner to start the environment
automationsFile?: AutomationsFile { automationsFilePath, session, triggerFilter } automations_file is the automations file spec of the environment
automations_file is the automations file spec of the environment
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('^$|^[^/].*')content?: Content { gitEmail, gitUsername, initializer, session } content is the content spec of the environment
content is the content spec of the environment
initializer configures how the environment is to be initialized
initializer configures how the environment is to be initialized
specs?: Array<Spec>
git?: Git { checkoutLocation, cloneTarget, remoteUri, 2 more }
devcontainer?: Devcontainer { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more } devcontainer is the devcontainer spec of the environment
devcontainer is the devcontainer spec of the environment
default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found
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('^$|^[^/].*')dotfiles?: Dotfiles { repository } Experimental: dotfiles is the dotfiles configuration of the devcontainer
Experimental: dotfiles is the dotfiles configuration of the devcontainer
URL of a dotfiles Git repository (e.g. https://github.com/owner/repository)
kernel_controls_config configures kernel-level controls for this environment
kernel_controls_config configures kernel-level controls for this environment
ports?: Array<Port>ports is the set of ports which ought to be exposed to your network
ports is the set of ports which ought to be exposed to your network
secrets?: Array<Secret>secrets are confidential data that is mounted into the environment
secrets are confidential data that is mounted into the environment
api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.
container_registry_basic_auth_host is the hostname of the container registry that supports basic auth
credentialProxy?: CredentialProxy { format, header, targetHosts } credential_proxy configures transparent credential injection via the
credential proxy. When set, the credential proxy intercepts HTTPS
traffic to the target hosts and replaces the dummy secret value with
the real value in the specified HTTP header. The real secret value is
never exposed in the environment.
This field is orthogonal to mount — a secret can be both mounted (e.g.
as a git credential) and proxied at the same time.
credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time.
scope?: "SCOPE_UNSPECIFIED" | "SCOPE_ORGANIZATION" | "SCOPE_PROJECT" | 3 morescope indicates where this secret originated from.
Used to filter secrets during build (only org and project secrets are injected).
scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).
version of the spec. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b.
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys are the public keys used to ssh into the environment
ssh_public_keys are the public keys used to ssh into the environment
Status is the current status of the environment
Status is the current status of the environment
activity_signal is the last activity signal for the environment.
activity_signal is the last activity signal for the environment.
automationsFile?: AutomationsFile { automationsFilePath, automationsFilePresence, failureMessage, 3 more } automations_file contains the status of the automations file.
automations_file contains the status of the automations file.
automations_file_path is the path to the automations file relative to the repo root.
automationsFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_ABSENT" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"automations_file_presence indicates how an automations file is present in the environment.
automations_file_presence indicates how an automations file is present in the environment.
failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED.
phase?: "CONTENT_PHASE_UNSPECIFIED" | "CONTENT_PHASE_CREATING" | "CONTENT_PHASE_INITIALIZING" | 4 morephase is the current phase of the automations file.
phase is the current phase of the automations file.
content?: Content { contentLocationInMachine, failureMessage, git, 3 more } content contains the status of the environment content.
content contains the status of the environment content.
content_location_in_machine is the location of the content in the machine
git?: Git { branch, changedFiles, cloneUrl, 4 more } git is the Git working copy status of the environment.
Note: this is a best-effort field and more often than not will not be
present. Its absence does not indicate the absence of a working copy.
git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy.
changedFiles?: Array<ChangedFile>changed_files is an array of changed files in the environment, possibly
truncated
changed_files is an array of changed files in the environment, possibly truncated
devcontainer?: Devcontainer { containerId, containerName, devcontainerconfigInSync, 9 more } devcontainer contains the status of the devcontainer.
devcontainer contains the status of the devcontainer.
container_name is the name of the container that is used to connect to the devcontainer
devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file.
devcontainer_file_path is the path to the devcontainer file relative to the repo root
devcontainerFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_GENERATED" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"devcontainer_file_presence indicates how the devcontainer file is present in the repo.
devcontainer_file_presence indicates how the devcontainer file is present in the repo.
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_RUNNING" | 2 morephase is the current phase of the devcontainer
phase is the current phase of the devcontainer
remote_workspace_folder is the folder that is used to connect to the devcontainer
environmentUrls?: EnvironmentURLs { logs, ops, ports, 2 more } environment_url contains the URL at which the environment can be accessed.
This field is only set if the environment is running.
environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running.
failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state.
machine?: Machine { failureMessage, phase, session, 3 more } machine contains the status of the environment machine
machine contains the status of the environment machine
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_STARTING" | 5 morephase is the current phase of the environment machine
phase is the current phase of the environment machine
timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out.
the phase of an environment is a simple, high-level summary of where the
environment is in its lifecycle
the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle
runnerAck?: RunnerAck { message, specVersion, statusCode } runner_ack contains the acknowledgement from the runner that is has
received the environment spec.
runner_ack contains the acknowledgement from the runner that is has received the environment spec.
secrets?: Array<Secret>secrets contains the status of the environment secrets
secrets contains the status of the environment secrets
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys contains the status of the environment ssh public keys
ssh_public_keys contains the status of the environment ssh public keys
version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
EnvironmentRetrieveResponse { environment }
+resource get environment
+resource get environment
ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager
Metadata is data associated with this environment that’s required for other
parts of Gitpod to function
Metadata is data associated with this environment that’s required for other parts of Gitpod to function
annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented
Time when the Environment was archived. If not set, the environment is not archived.
Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called).
lockdown_at is the time at which the environment becomes locked down due to the organization’s maximum environment lifetime policy. Nil when no lifetime policy applies.
organization_id is the ID of the organization that contains the environment
original_context_url is the normalized URL from which the environment was created
prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild.
If the Environment was started from a project, the project_id will reference the project.
Spec is the configuration of the environment that’s required for the
runner to start the environment
Spec is the configuration of the environment that’s required for the runner to start the environment
automationsFile?: AutomationsFile { automationsFilePath, session, triggerFilter } automations_file is the automations file spec of the environment
automations_file is the automations file spec of the environment
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('^$|^[^/].*')content?: Content { gitEmail, gitUsername, initializer, session } content is the content spec of the environment
content is the content spec of the environment
initializer configures how the environment is to be initialized
initializer configures how the environment is to be initialized
specs?: Array<Spec>
git?: Git { checkoutLocation, cloneTarget, remoteUri, 2 more }
devcontainer?: Devcontainer { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more } devcontainer is the devcontainer spec of the environment
devcontainer is the devcontainer spec of the environment
default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found
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('^$|^[^/].*')dotfiles?: Dotfiles { repository } Experimental: dotfiles is the dotfiles configuration of the devcontainer
Experimental: dotfiles is the dotfiles configuration of the devcontainer
URL of a dotfiles Git repository (e.g. https://github.com/owner/repository)
kernel_controls_config configures kernel-level controls for this environment
kernel_controls_config configures kernel-level controls for this environment
ports?: Array<Port>ports is the set of ports which ought to be exposed to your network
ports is the set of ports which ought to be exposed to your network
secrets?: Array<Secret>secrets are confidential data that is mounted into the environment
secrets are confidential data that is mounted into the environment
api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.
container_registry_basic_auth_host is the hostname of the container registry that supports basic auth
credentialProxy?: CredentialProxy { format, header, targetHosts } credential_proxy configures transparent credential injection via the
credential proxy. When set, the credential proxy intercepts HTTPS
traffic to the target hosts and replaces the dummy secret value with
the real value in the specified HTTP header. The real secret value is
never exposed in the environment.
This field is orthogonal to mount — a secret can be both mounted (e.g.
as a git credential) and proxied at the same time.
credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time.
scope?: "SCOPE_UNSPECIFIED" | "SCOPE_ORGANIZATION" | "SCOPE_PROJECT" | 3 morescope indicates where this secret originated from.
Used to filter secrets during build (only org and project secrets are injected).
scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).
version of the spec. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b.
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys are the public keys used to ssh into the environment
ssh_public_keys are the public keys used to ssh into the environment
Status is the current status of the environment
Status is the current status of the environment
activity_signal is the last activity signal for the environment.
activity_signal is the last activity signal for the environment.
automationsFile?: AutomationsFile { automationsFilePath, automationsFilePresence, failureMessage, 3 more } automations_file contains the status of the automations file.
automations_file contains the status of the automations file.
automations_file_path is the path to the automations file relative to the repo root.
automationsFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_ABSENT" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"automations_file_presence indicates how an automations file is present in the environment.
automations_file_presence indicates how an automations file is present in the environment.
failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED.
phase?: "CONTENT_PHASE_UNSPECIFIED" | "CONTENT_PHASE_CREATING" | "CONTENT_PHASE_INITIALIZING" | 4 morephase is the current phase of the automations file.
phase is the current phase of the automations file.
content?: Content { contentLocationInMachine, failureMessage, git, 3 more } content contains the status of the environment content.
content contains the status of the environment content.
content_location_in_machine is the location of the content in the machine
git?: Git { branch, changedFiles, cloneUrl, 4 more } git is the Git working copy status of the environment.
Note: this is a best-effort field and more often than not will not be
present. Its absence does not indicate the absence of a working copy.
git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy.
changedFiles?: Array<ChangedFile>changed_files is an array of changed files in the environment, possibly
truncated
changed_files is an array of changed files in the environment, possibly truncated
devcontainer?: Devcontainer { containerId, containerName, devcontainerconfigInSync, 9 more } devcontainer contains the status of the devcontainer.
devcontainer contains the status of the devcontainer.
container_name is the name of the container that is used to connect to the devcontainer
devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file.
devcontainer_file_path is the path to the devcontainer file relative to the repo root
devcontainerFilePresence?: "PRESENCE_UNSPECIFIED" | "PRESENCE_GENERATED" | "PRESENCE_DISCOVERED" | "PRESENCE_SPECIFIED"devcontainer_file_presence indicates how the devcontainer file is present in the repo.
devcontainer_file_presence indicates how the devcontainer file is present in the repo.
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_RUNNING" | 2 morephase is the current phase of the devcontainer
phase is the current phase of the devcontainer
remote_workspace_folder is the folder that is used to connect to the devcontainer
environmentUrls?: EnvironmentURLs { logs, ops, ports, 2 more } environment_url contains the URL at which the environment can be accessed.
This field is only set if the environment is running.
environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running.
failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state.
machine?: Machine { failureMessage, phase, session, 3 more } machine contains the status of the environment machine
machine contains the status of the environment machine
phase?: "PHASE_UNSPECIFIED" | "PHASE_CREATING" | "PHASE_STARTING" | 5 morephase is the current phase of the environment machine
phase is the current phase of the environment machine
timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out.
the phase of an environment is a simple, high-level summary of where the
environment is in its lifecycle
the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle
runnerAck?: RunnerAck { message, specVersion, statusCode } runner_ack contains the acknowledgement from the runner that is has
received the environment spec.
runner_ack contains the acknowledgement from the runner that is has received the environment spec.
secrets?: Array<Secret>secrets contains the status of the environment secrets
secrets contains the status of the environment secrets
sshPublicKeys?: Array<SSHPublicKey>ssh_public_keys contains the status of the environment ssh public keys
ssh_public_keys contains the status of the environment ssh public keys
version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
EnvironmentsAutomations
UpsertAutomationsFile
ModelsExpand Collapse
AutomationsFile { services, tasks } WARN: Do not remove any field here, as it will break reading automation yaml files. We error if there are any
unknown fields in the yaml (to ensure the yaml is correct), but would break if we removed any fields.
This includes marking a field as “reserved” in the proto file, this will also break reading the yaml.
WARN: Do not remove any field here, as it will break reading automation yaml files. We error if there are any unknown fields in the yaml (to ensure the yaml is correct), but would break if we removed any fields. This includes marking a field as “reserved” in the proto file, this will also break reading the yaml.
services?: Record<string, Services>
commands?: Commands { ready, start, stop }
ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code.
start is the command to start and run the service. If start exits, the service will transition to the following phase:
- Stopped: if the exit code is 0
- Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal.
stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands.
EnvironmentsAutomationsServices
CreateService
DeleteService
ListServices
GetService
StartService
StopService
UpdateService
ModelsExpand Collapse
Service { id, environmentId, metadata, 2 more }
description is a user-facing description for the service. It can be used to provide context and documentation for the service.
name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service.
reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI).
commands?: Commands { ready, start, stop } commands contains the commands to start, stop and check the readiness of the service
commands contains the commands to start, stop and check the readiness of the service
ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code.
start is the command to start and run the service. If start exits, the service will transition to the following phase:
- Stopped: if the exit code is 0
- Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal.
stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands.
env specifies environment variables for the service.
env specifies environment variables for the service.
failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state.
output contains the output of the service. setting an output field to empty string will unset it.
version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
ServiceMetadata { createdAt, creator, description, 4 more }
description is a user-facing description for the service. It can be used to provide context and documentation for the service.
name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service.
reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI).
ServiceSpec { commands, desiredPhase, env, 3 more }
commands?: Commands { ready, start, stop } commands contains the commands to start, stop and check the readiness of the service
commands contains the commands to start, stop and check the readiness of the service
ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code.
start is the command to start and run the service. If start exits, the service will transition to the following phase:
- Stopped: if the exit code is 0
- Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal.
stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands.
env specifies environment variables for the service.
env specifies environment variables for the service.
ServiceStatus { failureMessage, logUrl, output, 3 more }
failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state.
output contains the output of the service. setting an output field to empty string will unset it.
version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
ServiceCreateResponse { service }
description is a user-facing description for the service. It can be used to provide context and documentation for the service.
name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service.
reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI).
commands?: Commands { ready, start, stop } commands contains the commands to start, stop and check the readiness of the service
commands contains the commands to start, stop and check the readiness of the service
ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code.
start is the command to start and run the service. If start exits, the service will transition to the following phase:
- Stopped: if the exit code is 0
- Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal.
stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands.
env specifies environment variables for the service.
env specifies environment variables for the service.
failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state.
output contains the output of the service. setting an output field to empty string will unset it.
version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
ServiceRetrieveResponse { service }
description is a user-facing description for the service. It can be used to provide context and documentation for the service.
name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service.
reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI).
commands?: Commands { ready, start, stop } commands contains the commands to start, stop and check the readiness of the service
commands contains the commands to start, stop and check the readiness of the service
ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code.
start is the command to start and run the service. If start exits, the service will transition to the following phase:
- Stopped: if the exit code is 0
- Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal.
stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands.
env specifies environment variables for the service.
env specifies environment variables for the service.
failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state.
output contains the output of the service. setting an output field to empty string will unset it.
version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
EnvironmentsAutomationsTasks
CreateTask
DeleteTask
GetTask
StartTask
UpdateTask
ModelsExpand Collapse
TaskCreateResponse { task }
description is a user-facing description for the task. It can be used to provide context and documentation for the task.
name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task.
reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI).
TaskRetrieveResponse { task }
description is a user-facing description for the task. It can be used to provide context and documentation for the task.
name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task.
reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI).
TaskStartResponse { taskExecution }
desired_phase is the phase the task execution should be in. Used to stop a running task execution early.
desired_phase is the phase the task execution should be in. Used to stop a running task execution early.
plan?: Array<Plan>plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially.
The order of the groups is the order in which they are executed.
plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed.
failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state.
log_url is the URL to the logs of the task’s steps. If this is empty, the task either has no logs or has not yet started.
version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
steps?: Array<Step>steps provides the status for each individual step of the task execution. If a step is missing it
has not yet started.
steps provides the status for each individual step of the task execution. If a step is missing it has not yet started.
failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state.
output contains the output of the task execution. setting an output field to empty string will unset it.
EnvironmentsAutomationsTasksExecutions
ListTaskExecutions
GetTaskExecution
StopTaskExecution
ModelsExpand Collapse
ExecutionRetrieveResponse { taskExecution }
desired_phase is the phase the task execution should be in. Used to stop a running task execution early.
desired_phase is the phase the task execution should be in. Used to stop a running task execution early.
plan?: Array<Plan>plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially.
The order of the groups is the order in which they are executed.
plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed.
failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state.
log_url is the URL to the logs of the task’s steps. If this is empty, the task either has no logs or has not yet started.
version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.
steps?: Array<Step>steps provides the status for each individual step of the task execution. If a step is missing it
has not yet started.
steps provides the status for each individual step of the task execution. If a step is missing it has not yet started.
failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state.
output contains the output of the task execution. setting an output field to empty string will unset it.