Automations
UpsertAutomationsFile
ModelsExpand Collapse
AutomationsFile object { 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: optional map[object { commands, description, name, 3 more } ]
commands: optional object { 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.
AutomationsServices
CreateService
DeleteService
ListServices
GetService
StartService
StopService
UpdateService
ModelsExpand Collapse
Service object { 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).
triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } triggered_by is a list of trigger that start the service.
triggered_by is a list of trigger that start the service.
commands: optional object { 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 object { 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).
triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } triggered_by is a list of trigger that start the service.
triggered_by is a list of trigger that start the service.
ServiceSpec object { commands, desiredPhase, env, 3 more }
commands: optional object { 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 object { 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 object { 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).
triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } triggered_by is a list of trigger that start the service.
triggered_by is a list of trigger that start the service.
commands: optional object { 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 object { 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).
triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } triggered_by is a list of trigger that start the service.
triggered_by is a list of trigger that start the service.
commands: optional object { 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.
AutomationsTasks
CreateTask
DeleteTask
ListTasks
GetTask
StartTask
UpdateTask
ModelsExpand Collapse
TaskCreateResponse object { task }
dependencies specifies the IDs of the automations this task depends on.
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).
triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } triggered_by is a list of trigger that start the task.
triggered_by is a list of trigger that start the task.
TaskRetrieveResponse object { task }
dependencies specifies the IDs of the automations this task depends on.
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).
triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } triggered_by is a list of trigger that start the task.
triggered_by is a list of trigger that start the task.
TaskStartResponse object { taskExecution }
creator describes the principal who created/started the task run.
creator describes the principal who created/started the task run.
environment_id is the ID of the environment in which the task run is executed.
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: optional array of object { steps } 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: optional array of object { id, failureMessage, output, phase } 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.
AutomationsTasksExecutions
ListTaskExecutions
GetTaskExecution
StopTaskExecution
ModelsExpand Collapse
ExecutionRetrieveResponse object { taskExecution }
creator describes the principal who created/started the task run.
creator describes the principal who created/started the task run.
environment_id is the ID of the environment in which the task run is executed.
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: optional array of object { steps } 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: optional array of object { id, failureMessage, output, phase } 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.