API Reference

Environments

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Automations

UpsertAutomationsFile

client.environments.automations.upsert(AutomationUpsertParams { automationsFile, environmentId } body, RequestOptionsoptions?): AutomationUpsertResponse { updatedServiceIds, updatedTaskIds }

POST/gitpod.v1.EnvironmentAutomationService/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.

services?: Record<string, Services>

commands?: Commands { ready, start, stop }

ready?: string

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

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.

minLength1

stop?: string

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.

description?: string

name?: string

minLength1

role?: "" | "default" | "editor" | "ai-agent"

One of the following:

""

"default"

"editor"

"ai-agent"

runsOn?: RunsOn { docker, machine }

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

triggeredBy?: Array<"manual" | "postEnvironmentStart" | "postDevcontainerStart" | "prebuild">

One of the following:

"manual"

"postEnvironmentStart"

"postDevcontainerStart"

"prebuild"

tasks?: Record<string, Tasks>

command?: string

minLength1

dependsOn?: Array<string>

description?: string

name?: string

minLength1

runsOn?: RunsOn { docker, machine }

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

triggeredBy?: Array<"manual" | "postEnvironmentStart" | "postDevcontainerStart" | "prebuild">

One of the following:

"manual"

"postEnvironmentStart"

"postDevcontainerStart"

"prebuild"

AutomationUpsertResponse { updatedServiceIds, updatedTaskIds }

updatedServiceIds?: Array<string>

updatedTaskIds?: Array<string>

AutomationsServices

CreateService

client.environments.automations.services.create(ServiceCreateParams { environmentId, metadata, spec } body, RequestOptionsoptions?): ServiceCreateResponse { service }

POST/gitpod.v1.EnvironmentAutomationService/CreateService

DeleteService

client.environments.automations.services.delete(ServiceDeleteParams { id, force } body, RequestOptionsoptions?): ServiceDeleteResponse

POST/gitpod.v1.EnvironmentAutomationService/DeleteService

ListServices

client.environments.automations.services.list(ServiceListParams { token, pageSize, filter, pagination } params, RequestOptionsoptions?): ServicesPage<Service { id, environmentId, metadata, 2 more } >

POST/gitpod.v1.EnvironmentAutomationService/ListServices

GetService

client.environments.automations.services.retrieve(ServiceRetrieveParams { id } body, RequestOptionsoptions?): ServiceRetrieveResponse { service }

POST/gitpod.v1.EnvironmentAutomationService/GetService

StartService

client.environments.automations.services.start(ServiceStartParams { id } body, RequestOptionsoptions?): ServiceStartResponse

POST/gitpod.v1.EnvironmentAutomationService/StartService

StopService

client.environments.automations.services.stop(ServiceStopParams { id } body, RequestOptionsoptions?): ServiceStopResponse

POST/gitpod.v1.EnvironmentAutomationService/StopService

UpdateService

client.environments.automations.services.update(ServiceUpdateParams { id, metadata, spec, status } body, RequestOptionsoptions?): ServiceUpdateResponse

POST/gitpod.v1.EnvironmentAutomationService/UpdateService

ModelsExpand Collapse

Service { id, environmentId, metadata, 2 more }

id: string

formatuuid

environmentId?: string

formatuuid

metadata?: ServiceMetadata { createdAt, creator, description, 4 more }

createdAt?: string

created_at is the time the service was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created the service.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description?: string

description is a user-facing description for the service. It can be used to provide context and documentation for the service.

name?: string

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.

minLength1

reference?: string

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

role?: ServiceRole

role specifies the intended role or purpose of the service.

One of the following:

"SERVICE_ROLE_UNSPECIFIED"

"SERVICE_ROLE_DEFAULT"

"SERVICE_ROLE_EDITOR"

"SERVICE_ROLE_AI_AGENT"

"SERVICE_ROLE_SECURITY_AGENT"

triggeredBy?: Array<AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } >

triggered_by is a list of trigger that start the service.

beforeSnapshot?: boolean

manual?: boolean

postDevcontainerStart?: boolean

postEnvironmentStart?: boolean

postMachineStart?: boolean

prebuild?: boolean

spec?: 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

ready?: string

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

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.

minLength1

stop?: string

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.

desiredPhase?: ServicePhase

desired_phase is the phase the service should be in. Used to start or stop the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the service.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the service should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

session?: string

session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed.

specVersion?: string

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.

status?: ServiceStatus { failureMessage, logUrl, output, 3 more }

failureMessage?: string

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.

logUrl?: string

log_url contains the URL at which the service logs can be accessed.

output?: Record<string, string>

output contains the output of the service. setting an output field to empty string will unset it.

phase?: ServicePhase

phase is the current phase of the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

session?: string

session is the current session of the service.

statusVersion?: string

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 }

createdAt?: string

created_at is the time the service was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created the service.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description?: string

description is a user-facing description for the service. It can be used to provide context and documentation for the service.

name?: string

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.

minLength1

reference?: string

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

role?: ServiceRole

role specifies the intended role or purpose of the service.

One of the following:

"SERVICE_ROLE_UNSPECIFIED"

"SERVICE_ROLE_DEFAULT"

"SERVICE_ROLE_EDITOR"

"SERVICE_ROLE_AI_AGENT"

"SERVICE_ROLE_SECURITY_AGENT"

triggeredBy?: Array<AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } >

triggered_by is a list of trigger that start the service.

beforeSnapshot?: boolean

manual?: boolean

postDevcontainerStart?: boolean

postEnvironmentStart?: boolean

postMachineStart?: boolean

prebuild?: boolean

ServicePhase = "SERVICE_PHASE_UNSPECIFIED" | "SERVICE_PHASE_STARTING" | "SERVICE_PHASE_RUNNING" | 4 more

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

ServiceRole = "SERVICE_ROLE_UNSPECIFIED" | "SERVICE_ROLE_DEFAULT" | "SERVICE_ROLE_EDITOR" | 2 more

One of the following:

"SERVICE_ROLE_UNSPECIFIED"

"SERVICE_ROLE_DEFAULT"

"SERVICE_ROLE_EDITOR"

"SERVICE_ROLE_AI_AGENT"

"SERVICE_ROLE_SECURITY_AGENT"

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

ready?: string

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

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.

minLength1

stop?: string

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.

desiredPhase?: ServicePhase

desired_phase is the phase the service should be in. Used to start or stop the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the service.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the service should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

session?: string

session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed.

specVersion?: string

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.

ServiceStatus { failureMessage, logUrl, output, 3 more }

failureMessage?: string

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.

logUrl?: string

log_url contains the URL at which the service logs can be accessed.

output?: Record<string, string>

output contains the output of the service. setting an output field to empty string will unset it.

phase?: ServicePhase

phase is the current phase of the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

session?: string

session is the current session of the service.

statusVersion?: string

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 }

service: Service { id, environmentId, metadata, 2 more }

id: string

formatuuid

environmentId?: string

formatuuid

metadata?: ServiceMetadata { createdAt, creator, description, 4 more }

createdAt?: string

created_at is the time the service was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created the service.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description?: string

description is a user-facing description for the service. It can be used to provide context and documentation for the service.

name?: string

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.

minLength1

reference?: string

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

role?: ServiceRole

role specifies the intended role or purpose of the service.

One of the following:

"SERVICE_ROLE_UNSPECIFIED"

"SERVICE_ROLE_DEFAULT"

"SERVICE_ROLE_EDITOR"

"SERVICE_ROLE_AI_AGENT"

"SERVICE_ROLE_SECURITY_AGENT"

triggeredBy?: Array<AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } >

triggered_by is a list of trigger that start the service.

beforeSnapshot?: boolean

manual?: boolean

postDevcontainerStart?: boolean

postEnvironmentStart?: boolean

postMachineStart?: boolean

prebuild?: boolean

spec?: 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

ready?: string

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

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.

minLength1

stop?: string

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.

desiredPhase?: ServicePhase

desired_phase is the phase the service should be in. Used to start or stop the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the service.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the service should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

session?: string

session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed.

specVersion?: string

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.

status?: ServiceStatus { failureMessage, logUrl, output, 3 more }

failureMessage?: string

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.

logUrl?: string

log_url contains the URL at which the service logs can be accessed.

output?: Record<string, string>

output contains the output of the service. setting an output field to empty string will unset it.

phase?: ServicePhase

phase is the current phase of the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

session?: string

session is the current session of the service.

statusVersion?: string

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.

ServiceDeleteResponse = unknown

ServiceRetrieveResponse { service }

service: Service { id, environmentId, metadata, 2 more }

id: string

formatuuid

environmentId?: string

formatuuid

metadata?: ServiceMetadata { createdAt, creator, description, 4 more }

createdAt?: string

created_at is the time the service was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created the service.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description?: string

description is a user-facing description for the service. It can be used to provide context and documentation for the service.

name?: string

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.

minLength1

reference?: string

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

role?: ServiceRole

role specifies the intended role or purpose of the service.

One of the following:

"SERVICE_ROLE_UNSPECIFIED"

"SERVICE_ROLE_DEFAULT"

"SERVICE_ROLE_EDITOR"

"SERVICE_ROLE_AI_AGENT"

"SERVICE_ROLE_SECURITY_AGENT"

triggeredBy?: Array<AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } >

triggered_by is a list of trigger that start the service.

beforeSnapshot?: boolean

manual?: boolean

postDevcontainerStart?: boolean

postEnvironmentStart?: boolean

postMachineStart?: boolean

prebuild?: boolean

spec?: 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

ready?: string

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

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.

minLength1

stop?: string

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.

desiredPhase?: ServicePhase

desired_phase is the phase the service should be in. Used to start or stop the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the service.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the service should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

session?: string

session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed.

specVersion?: string

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.

status?: ServiceStatus { failureMessage, logUrl, output, 3 more }

failureMessage?: string

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.

logUrl?: string

log_url contains the URL at which the service logs can be accessed.

output?: Record<string, string>

output contains the output of the service. setting an output field to empty string will unset it.

phase?: ServicePhase

phase is the current phase of the service.

One of the following:

"SERVICE_PHASE_UNSPECIFIED"

"SERVICE_PHASE_STARTING"

"SERVICE_PHASE_RUNNING"

"SERVICE_PHASE_STOPPING"

"SERVICE_PHASE_STOPPED"

"SERVICE_PHASE_FAILED"

"SERVICE_PHASE_DELETED"

session?: string

session is the current session of the service.

statusVersion?: string

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.

ServiceStartResponse = unknown

ServiceStopResponse = unknown

ServiceUpdateResponse = unknown

AutomationsTasks

CreateTask

client.environments.automations.tasks.create(TaskCreateParams { dependsOn, environmentId, metadata, spec } body, RequestOptionsoptions?): TaskCreateResponse { task }

POST/gitpod.v1.EnvironmentAutomationService/CreateTask

DeleteTask

client.environments.automations.tasks.delete(TaskDeleteParams { id } body, RequestOptionsoptions?): TaskDeleteResponse

POST/gitpod.v1.EnvironmentAutomationService/DeleteTask

ListTasks

client.environments.automations.tasks.list(TaskListParams { token, pageSize, filter, pagination } params, RequestOptionsoptions?): TasksPage<Task { id, dependsOn, environmentId, 2 more } >

POST/gitpod.v1.EnvironmentAutomationService/ListTasks

GetTask

client.environments.automations.tasks.retrieve(TaskRetrieveParams { id } body, RequestOptionsoptions?): TaskRetrieveResponse { task }

POST/gitpod.v1.EnvironmentAutomationService/GetTask

StartTask

client.environments.automations.tasks.start(TaskStartParams { id } body, RequestOptionsoptions?): TaskStartResponse { taskExecution }

POST/gitpod.v1.EnvironmentAutomationService/StartTask

UpdateTask

client.environments.automations.tasks.update(TaskUpdateParams { id, dependsOn, metadata, spec } body, RequestOptionsoptions?): TaskUpdateResponse

POST/gitpod.v1.EnvironmentAutomationService/UpdateTask

ModelsExpand Collapse

TaskCreateResponse { task }

task: Task { id, dependsOn, environmentId, 2 more }

id: string

formatuuid

dependsOn?: Array<string>

dependencies specifies the IDs of the automations this task depends on.

environmentId?: string

formatuuid

metadata?: TaskMetadata { createdAt, creator, description, 3 more }

createdAt?: string

created_at is the time the task was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created the task.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description?: string

description is a user-facing description for the task. It can be used to provide context and documentation for the task.

name?: string

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.

minLength1

reference?: string

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

triggeredBy?: Array<AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } >

triggered_by is a list of trigger that start the task.

beforeSnapshot?: boolean

manual?: boolean

postDevcontainerStart?: boolean

postEnvironmentStart?: boolean

postMachineStart?: boolean

prebuild?: boolean

spec?: TaskSpec { command, env, runsOn }

command?: string

command contains the command the task should execute

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the task.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the task should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

TaskDeleteResponse = unknown

TaskRetrieveResponse { task }

task: Task { id, dependsOn, environmentId, 2 more }

id: string

formatuuid

dependsOn?: Array<string>

dependencies specifies the IDs of the automations this task depends on.

environmentId?: string

formatuuid

metadata?: TaskMetadata { createdAt, creator, description, 3 more }

createdAt?: string

created_at is the time the task was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created the task.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description?: string

description is a user-facing description for the task. It can be used to provide context and documentation for the task.

name?: string

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.

minLength1

reference?: string

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

triggeredBy?: Array<AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } >

triggered_by is a list of trigger that start the task.

beforeSnapshot?: boolean

manual?: boolean

postDevcontainerStart?: boolean

postEnvironmentStart?: boolean

postMachineStart?: boolean

prebuild?: boolean

spec?: TaskSpec { command, env, runsOn }

command?: string

command contains the command the task should execute

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the task.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the task should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

TaskStartResponse { taskExecution }

taskExecution: TaskExecution { id, metadata, spec, status }

id: string

formatuuid

metadata?: TaskExecutionMetadata { completedAt, createdAt, creator, 4 more }

completedAt?: string

completed_at is the time the task execution was done.

formatdate-time

createdAt?: string

created_at is the time the task was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created/started the task run.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

environmentId?: string

environment_id is the ID of the environment in which the task run is executed.

formatuuid

startedAt?: string

started_at is the time the task execution actually started to run.

formatdate-time

startedBy?: string

started_by describes the trigger that started the task execution.

taskId?: string

task_id is the ID of the main task being executed.

formatuuid

spec?: TaskExecutionSpec { desiredPhase, plan }

desiredPhase?: TaskExecutionPhase

desired_phase is the phase the task execution should be in. Used to stop a running task execution early.

One of the following:

"TASK_EXECUTION_PHASE_UNSPECIFIED"

"TASK_EXECUTION_PHASE_PENDING"

"TASK_EXECUTION_PHASE_RUNNING"

"TASK_EXECUTION_PHASE_SUCCEEDED"

"TASK_EXECUTION_PHASE_FAILED"

"TASK_EXECUTION_PHASE_STOPPED"

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.

steps?: Array<Step>

id?: string

ID is the ID of the execution step

formatuuid

dependsOn?: Array<string>

label?: string

serviceId?: string

formatuuid

task?: Task { id, spec }

id?: string

formatuuid

spec?: TaskSpec { command, env, runsOn }

command?: string

command contains the command the task should execute

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the task.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the task should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

status?: TaskExecutionStatus { failureMessage, logUrl, phase, 2 more }

failureMessage?: string

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.

logUrl?: string

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.

phase?: TaskExecutionPhase

the phase of a task execution represents the aggregated phase of all steps.

One of the following:

"TASK_EXECUTION_PHASE_UNSPECIFIED"

"TASK_EXECUTION_PHASE_PENDING"

"TASK_EXECUTION_PHASE_RUNNING"

"TASK_EXECUTION_PHASE_SUCCEEDED"

"TASK_EXECUTION_PHASE_FAILED"

"TASK_EXECUTION_PHASE_STOPPED"

statusVersion?: string

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.

id?: string

ID is the ID of the execution step

formatuuid

failureMessage?: string

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?: Record<string, string>

output contains the output of the task execution. setting an output field to empty string will unset it.

phase?: TaskExecutionPhase

phase is the current phase of the execution step

One of the following:

"TASK_EXECUTION_PHASE_UNSPECIFIED"

"TASK_EXECUTION_PHASE_PENDING"

"TASK_EXECUTION_PHASE_RUNNING"

"TASK_EXECUTION_PHASE_SUCCEEDED"

"TASK_EXECUTION_PHASE_FAILED"

"TASK_EXECUTION_PHASE_STOPPED"

TaskUpdateResponse = unknown

AutomationsTasksExecutions

ListTaskExecutions

client.environments.automations.tasks.executions.list(ExecutionListParams { token, pageSize, filter, pagination } params, RequestOptionsoptions?): TaskExecutionsPage<TaskExecution { id, metadata, spec, status } >

POST/gitpod.v1.EnvironmentAutomationService/ListTaskExecutions

GetTaskExecution

client.environments.automations.tasks.executions.retrieve(ExecutionRetrieveParams { id } body, RequestOptionsoptions?): ExecutionRetrieveResponse { taskExecution }

POST/gitpod.v1.EnvironmentAutomationService/GetTaskExecution

StopTaskExecution

client.environments.automations.tasks.executions.stop(ExecutionStopParams { id } body, RequestOptionsoptions?): ExecutionStopResponse

POST/gitpod.v1.EnvironmentAutomationService/StopTaskExecution

ModelsExpand Collapse

ExecutionRetrieveResponse { taskExecution }

taskExecution: TaskExecution { id, metadata, spec, status }

id: string

formatuuid

metadata?: TaskExecutionMetadata { completedAt, createdAt, creator, 4 more }

completedAt?: string

completed_at is the time the task execution was done.

formatdate-time

createdAt?: string

created_at is the time the task was created.

formatdate-time

creator?: Subject { id, principal }

creator describes the principal who created/started the task run.

id?: string

id is the UUID of the subject

formatuuid

principal?: Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

environmentId?: string

environment_id is the ID of the environment in which the task run is executed.

formatuuid

startedAt?: string

started_at is the time the task execution actually started to run.

formatdate-time

startedBy?: string

started_by describes the trigger that started the task execution.

taskId?: string

task_id is the ID of the main task being executed.

formatuuid

spec?: TaskExecutionSpec { desiredPhase, plan }

desiredPhase?: TaskExecutionPhase

desired_phase is the phase the task execution should be in. Used to stop a running task execution early.

One of the following:

"TASK_EXECUTION_PHASE_UNSPECIFIED"

"TASK_EXECUTION_PHASE_PENDING"

"TASK_EXECUTION_PHASE_RUNNING"

"TASK_EXECUTION_PHASE_SUCCEEDED"

"TASK_EXECUTION_PHASE_FAILED"

"TASK_EXECUTION_PHASE_STOPPED"

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.

steps?: Array<Step>

id?: string

ID is the ID of the execution step

formatuuid

dependsOn?: Array<string>

label?: string

serviceId?: string

formatuuid

task?: Task { id, spec }

id?: string

formatuuid

spec?: TaskSpec { command, env, runsOn }

command?: string

command contains the command the task should execute

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the task.

name?: string

name is the environment variable name.

minLength1

value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid

runsOn?: RunsOn { docker, machine }

runs_on specifies the environment the task should run on.

docker?: Docker { environment, image }

environment?: Array<string>

image?: string

minLength1

machine?: unknown

Machine runs the service/task directly on the VM/machine level.

status?: TaskExecutionStatus { failureMessage, logUrl, phase, 2 more }

failureMessage?: string

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.

logUrl?: string

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.

phase?: TaskExecutionPhase

the phase of a task execution represents the aggregated phase of all steps.

One of the following:

"TASK_EXECUTION_PHASE_UNSPECIFIED"

"TASK_EXECUTION_PHASE_PENDING"

"TASK_EXECUTION_PHASE_RUNNING"

"TASK_EXECUTION_PHASE_SUCCEEDED"

"TASK_EXECUTION_PHASE_FAILED"

"TASK_EXECUTION_PHASE_STOPPED"

statusVersion?: string

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.

id?: string

ID is the ID of the execution step

formatuuid

failureMessage?: string

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?: Record<string, string>

output contains the output of the task execution. setting an output field to empty string will unset it.

phase?: TaskExecutionPhase

phase is the current phase of the execution step

One of the following:

"TASK_EXECUTION_PHASE_UNSPECIFIED"

"TASK_EXECUTION_PHASE_PENDING"

"TASK_EXECUTION_PHASE_RUNNING"

"TASK_EXECUTION_PHASE_SUCCEEDED"

"TASK_EXECUTION_PHASE_FAILED"

"TASK_EXECUTION_PHASE_STOPPED"

ExecutionStopResponse = unknown