Skip to content
Ona API Reference
Ona Docs
API Reference
Environments

Automations

UpsertAutomationsFile
environments.automations.upsert(AutomationUpsertParams**kwargs) -> AutomationUpsertResponse
POST/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile
ModelsExpand Collapse
class AutomationsFile: …

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: Optional[Dict[str, Services]]
commands: Optional[ServicesCommands]
ready: Optional[str]

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

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

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: Optional[str]
name: Optional[str]
minLength1
role: Optional[Literal["", "default", "editor", "ai-agent"]]
One of the following:
""
"default"
"editor"
"ai-agent"
runs_on: Optional[RunsOn]
docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

triggered_by: Optional[List[Literal["manual", "postEnvironmentStart", "postDevcontainerStart", "prebuild"]]]
One of the following:
"manual"
"postEnvironmentStart"
"postDevcontainerStart"
"prebuild"
tasks: Optional[Dict[str, Tasks]]
command: Optional[str]
minLength1
depends_on: Optional[List[str]]
description: Optional[str]
name: Optional[str]
minLength1
runs_on: Optional[RunsOn]
docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

triggered_by: Optional[List[Literal["manual", "postEnvironmentStart", "postDevcontainerStart", "prebuild"]]]
One of the following:
"manual"
"postEnvironmentStart"
"postDevcontainerStart"
"prebuild"
class AutomationUpsertResponse: …
updated_service_ids: Optional[List[str]]
updated_task_ids: Optional[List[str]]

AutomationsServices

CreateService
environments.automations.services.create(ServiceCreateParams**kwargs) -> ServiceCreateResponse
POST/gitpod.v1.EnvironmentAutomationService/CreateService
DeleteService
environments.automations.services.delete(ServiceDeleteParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/DeleteService
ListServices
environments.automations.services.list(ServiceListParams**kwargs) -> SyncServicesPage[Service]
POST/gitpod.v1.EnvironmentAutomationService/ListServices
GetService
environments.automations.services.retrieve(ServiceRetrieveParams**kwargs) -> ServiceRetrieveResponse
POST/gitpod.v1.EnvironmentAutomationService/GetService
StartService
environments.automations.services.start(ServiceStartParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/StartService
StopService
environments.automations.services.stop(ServiceStopParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/StopService
UpdateService
environments.automations.services.update(ServiceUpdateParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/UpdateService
ModelsExpand Collapse
class Service: …
id: str
formatuuid
environment_id: Optional[str]
formatuuid
metadata: Optional[ServiceMetadata]
created_at: Optional[datetime]

created_at is the time the service was created.

formatdate-time
creator: Optional[Subject]

creator describes the principal who created the service.

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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: Optional[str]

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

name: Optional[str]

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

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: Optional[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"
triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the service.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
spec: Optional[ServiceSpec]
commands: Optional[Commands]

commands contains the commands to start, stop and check the readiness of the service

ready: Optional[str]

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

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

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.

desired_phase: Optional[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: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the service.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the service should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

session: Optional[str]

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.

spec_version: Optional[str]

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: Optional[ServiceStatus]
failure_message: Optional[str]

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.

log_url: Optional[str]

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

output: Optional[Dict[str, str]]

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

phase: Optional[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: Optional[str]

session is the current session of the service.

status_version: Optional[str]

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.

class ServiceMetadata: …
created_at: Optional[datetime]

created_at is the time the service was created.

formatdate-time
creator: Optional[Subject]

creator describes the principal who created the service.

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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: Optional[str]

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

name: Optional[str]

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

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: Optional[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"
triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the service.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
Literal["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"
Literal["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"
class ServiceSpec: …
commands: Optional[Commands]

commands contains the commands to start, stop and check the readiness of the service

ready: Optional[str]

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

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

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.

desired_phase: Optional[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: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the service.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the service should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

session: Optional[str]

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.

spec_version: Optional[str]

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.

class ServiceStatus: …
failure_message: Optional[str]

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.

log_url: Optional[str]

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

output: Optional[Dict[str, str]]

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

phase: Optional[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: Optional[str]

session is the current session of the service.

status_version: Optional[str]

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.

class ServiceCreateResponse: …
service: Service
id: str
formatuuid
environment_id: Optional[str]
formatuuid
metadata: Optional[ServiceMetadata]
created_at: Optional[datetime]

created_at is the time the service was created.

formatdate-time
creator: Optional[Subject]

creator describes the principal who created the service.

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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: Optional[str]

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

name: Optional[str]

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

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: Optional[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"
triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the service.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
spec: Optional[ServiceSpec]
commands: Optional[Commands]

commands contains the commands to start, stop and check the readiness of the service

ready: Optional[str]

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

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

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.

desired_phase: Optional[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: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the service.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the service should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

session: Optional[str]

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.

spec_version: Optional[str]

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: Optional[ServiceStatus]
failure_message: Optional[str]

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.

log_url: Optional[str]

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

output: Optional[Dict[str, str]]

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

phase: Optional[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: Optional[str]

session is the current session of the service.

status_version: Optional[str]

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.

class ServiceRetrieveResponse: …
service: Service
id: str
formatuuid
environment_id: Optional[str]
formatuuid
metadata: Optional[ServiceMetadata]
created_at: Optional[datetime]

created_at is the time the service was created.

formatdate-time
creator: Optional[Subject]

creator describes the principal who created the service.

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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: Optional[str]

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

name: Optional[str]

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

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: Optional[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"
triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the service.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
spec: Optional[ServiceSpec]
commands: Optional[Commands]

commands contains the commands to start, stop and check the readiness of the service

ready: Optional[str]

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

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

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.

desired_phase: Optional[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: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the service.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the service should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

session: Optional[str]

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.

spec_version: Optional[str]

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: Optional[ServiceStatus]
failure_message: Optional[str]

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.

log_url: Optional[str]

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

output: Optional[Dict[str, str]]

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

phase: Optional[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: Optional[str]

session is the current session of the service.

status_version: Optional[str]

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.

AutomationsTasks

CreateTask
environments.automations.tasks.create(TaskCreateParams**kwargs) -> TaskCreateResponse
POST/gitpod.v1.EnvironmentAutomationService/CreateTask
DeleteTask
environments.automations.tasks.delete(TaskDeleteParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/DeleteTask
ListTasks
environments.automations.tasks.list(TaskListParams**kwargs) -> SyncTasksPage[Task]
POST/gitpod.v1.EnvironmentAutomationService/ListTasks
GetTask
environments.automations.tasks.retrieve(TaskRetrieveParams**kwargs) -> TaskRetrieveResponse
POST/gitpod.v1.EnvironmentAutomationService/GetTask
StartTask
environments.automations.tasks.start(TaskStartParams**kwargs) -> TaskStartResponse
POST/gitpod.v1.EnvironmentAutomationService/StartTask
UpdateTask
environments.automations.tasks.update(TaskUpdateParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/UpdateTask
ModelsExpand Collapse
class TaskCreateResponse: …
task: Task
id: str
formatuuid
depends_on: Optional[List[str]]

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

environment_id: Optional[str]
formatuuid
metadata: Optional[TaskMetadata]
created_at: Optional[datetime]

created_at is the time the task was created.

formatdate-time
creator: Optional[Subject]

creator describes the principal who created the task.

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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: Optional[str]

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

name: Optional[str]

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

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

triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the task.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
spec: Optional[TaskSpec]
command: Optional[str]

command contains the command the task should execute

env: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the task.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the task should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

class TaskRetrieveResponse: …
task: Task
id: str
formatuuid
depends_on: Optional[List[str]]

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

environment_id: Optional[str]
formatuuid
metadata: Optional[TaskMetadata]
created_at: Optional[datetime]

created_at is the time the task was created.

formatdate-time
creator: Optional[Subject]

creator describes the principal who created the task.

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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: Optional[str]

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

name: Optional[str]

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

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

triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the task.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
spec: Optional[TaskSpec]
command: Optional[str]

command contains the command the task should execute

env: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the task.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the task should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

class TaskStartResponse: …
task_execution: TaskExecution
id: str
formatuuid
metadata: Optional[TaskExecutionMetadata]
completed_at: Optional[datetime]

completed_at is the time the task execution was done.

formatdate-time
created_at: Optional[datetime]

created_at is the time the task was created.

formatdate-time
creator: Optional[Subject]

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

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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"
environment_id: Optional[str]

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

formatuuid
started_at: Optional[datetime]

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

formatdate-time
started_by: Optional[str]

started_by describes the trigger that started the task execution.

task_id: Optional[str]

task_id is the ID of the main task being executed.

formatuuid
spec: Optional[TaskExecutionSpec]
desired_phase: Optional[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: Optional[List[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: Optional[List[PlanStep]]
id: Optional[str]

ID is the ID of the execution step

formatuuid
depends_on: Optional[List[str]]
label: Optional[str]
service_id: Optional[str]
formatuuid
task: Optional[PlanStepTask]
id: Optional[str]
formatuuid
spec: Optional[TaskSpec]
command: Optional[str]

command contains the command the task should execute

env: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the task.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the task should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

status: Optional[TaskExecutionStatus]
failure_message: Optional[str]

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

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: Optional[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"
status_version: Optional[str]

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: Optional[List[Step]]

steps provides the status for each individual step of the task execution. If a step is missing it has not yet started.

id: Optional[str]

ID is the ID of the execution step

formatuuid
failure_message: Optional[str]

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: Optional[Dict[str, str]]

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

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

AutomationsTasksExecutions

ListTaskExecutions
environments.automations.tasks.executions.list(ExecutionListParams**kwargs) -> SyncTaskExecutionsPage[TaskExecution]
POST/gitpod.v1.EnvironmentAutomationService/ListTaskExecutions
GetTaskExecution
environments.automations.tasks.executions.retrieve(ExecutionRetrieveParams**kwargs) -> ExecutionRetrieveResponse
POST/gitpod.v1.EnvironmentAutomationService/GetTaskExecution
StopTaskExecution
environments.automations.tasks.executions.stop(ExecutionStopParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/StopTaskExecution
ModelsExpand Collapse
class ExecutionRetrieveResponse: …
task_execution: TaskExecution
id: str
formatuuid
metadata: Optional[TaskExecutionMetadata]
completed_at: Optional[datetime]

completed_at is the time the task execution was done.

formatdate-time
created_at: Optional[datetime]

created_at is the time the task was created.

formatdate-time
creator: Optional[Subject]

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

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[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"
environment_id: Optional[str]

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

formatuuid
started_at: Optional[datetime]

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

formatdate-time
started_by: Optional[str]

started_by describes the trigger that started the task execution.

task_id: Optional[str]

task_id is the ID of the main task being executed.

formatuuid
spec: Optional[TaskExecutionSpec]
desired_phase: Optional[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: Optional[List[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: Optional[List[PlanStep]]
id: Optional[str]

ID is the ID of the execution step

formatuuid
depends_on: Optional[List[str]]
label: Optional[str]
service_id: Optional[str]
formatuuid
task: Optional[PlanStepTask]
id: Optional[str]
formatuuid
spec: Optional[TaskSpec]
command: Optional[str]

command contains the command the task should execute

env: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the task.

name: Optional[str]

name is the environment variable name.

minLength1
value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid
runs_on: Optional[RunsOn]

runs_on specifies the environment the task should run on.

docker: Optional[Docker]
environment: Optional[List[str]]
image: Optional[str]
minLength1
machine: Optional[object]

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

status: Optional[TaskExecutionStatus]
failure_message: Optional[str]

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

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: Optional[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"
status_version: Optional[str]

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: Optional[List[Step]]

steps provides the status for each individual step of the task execution. If a step is missing it has not yet started.

id: Optional[str]

ID is the ID of the execution step

formatuuid
failure_message: Optional[str]

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: Optional[Dict[str, str]]

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

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