Automations

UpsertAutomationsFile

client.Environments.Automations.Upsert(ctx, body) (*EnvironmentAutomationUpsertResponse, error)

POST/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile

ModelsExpand Collapse

type AutomationsFile struct{…}

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 map[string, AutomationsFileService]Optional

Commands AutomationsFileServicesCommandsOptional

Ready stringOptional

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 stringOptional

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 stringOptional

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 stringOptional

Name stringOptional

minLength1

ReadinessTimeout stringOptional

A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like “day” or “month”. It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.

Examples

Example 1: Compute Duration from two Timestamps in pseudo code.

 Timestamp start = ...;
 Timestamp end = ...;
 Duration duration = ...;

 duration.seconds = end.seconds - start.seconds;
 duration.nanos = end.nanos - start.nanos;

 if (duration.seconds < 0 && duration.nanos > 0) {
   duration.seconds += 1;
   duration.nanos -= 1000000000;
 } else if (duration.seconds > 0 && duration.nanos < 0) {
   duration.seconds -= 1;
   duration.nanos += 1000000000;
 }

Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.

 Timestamp start = ...;
 Duration duration = ...;
 Timestamp end = ...;

 end.seconds = start.seconds + duration.seconds;
 end.nanos = start.nanos + duration.nanos;

 if (end.nanos < 0) {
   end.seconds -= 1;
   end.nanos += 1000000000;
 } else if (end.nanos >= 1000000000) {
   end.seconds += 1;
   end.nanos -= 1000000000;
 }

Example 3: Compute Duration from datetime.timedelta in Python.

 td = datetime.timedelta(days=3, minutes=10)
 duration = Duration()
 duration.FromTimedelta(td)

JSON Mapping

In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix “s” (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as “3s”, while 3 seconds and 1 nanosecond should be expressed in JSON format as “3.000000001s”, and 3 seconds and 1 microsecond should be expressed in JSON format as “3.000001s”.

formatregex

Role AutomationsFileServicesRoleOptional

One of the following:

const AutomationsFileServicesRoleEmpty AutomationsFileServicesRole = ""

const AutomationsFileServicesRoleDefault AutomationsFileServicesRole = "default"

const AutomationsFileServicesRoleEditor AutomationsFileServicesRole = "editor"

const AutomationsFileServicesRoleAIAgent AutomationsFileServicesRole = "ai-agent"

RunsOn RunsOnOptional

Docker RunsOnDockerOptional

Environment []stringOptional

Image stringOptional

minLength1

Machine unknownOptional

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

TriggeredBy []AutomationsFileServicesTriggeredByOptional

One of the following:

const AutomationsFileServicesTriggeredByManual AutomationsFileServicesTriggeredBy = "manual"

const AutomationsFileServicesTriggeredByPostEnvironmentStart AutomationsFileServicesTriggeredBy = "postEnvironmentStart"

const AutomationsFileServicesTriggeredByPostDevcontainerStart AutomationsFileServicesTriggeredBy = "postDevcontainerStart"

const AutomationsFileServicesTriggeredByPrebuild AutomationsFileServicesTriggeredBy = "prebuild"

Tasks map[string, AutomationsFileTask]Optional

Command stringOptional

minLength1

DependsOn []stringOptional

Description stringOptional

Name stringOptional

minLength1

RunsOn RunsOnOptional

Docker RunsOnDockerOptional

Environment []stringOptional

Image stringOptional

minLength1

Machine unknownOptional

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

TriggeredBy []AutomationsFileTasksTriggeredByOptional

One of the following:

const AutomationsFileTasksTriggeredByManual AutomationsFileTasksTriggeredBy = "manual"

const AutomationsFileTasksTriggeredByPostEnvironmentStart AutomationsFileTasksTriggeredBy = "postEnvironmentStart"

const AutomationsFileTasksTriggeredByPostDevcontainerStart AutomationsFileTasksTriggeredBy = "postDevcontainerStart"

const AutomationsFileTasksTriggeredByPrebuild AutomationsFileTasksTriggeredBy = "prebuild"

AutomationsServices

CreateService

client.Environments.Automations.Services.New(ctx, body) (*EnvironmentAutomationServiceNewResponse, error)

POST/gitpod.v1.EnvironmentAutomationService/CreateService

DeleteService

client.Environments.Automations.Services.Delete(ctx, body) (*EnvironmentAutomationServiceDeleteResponse, error)

POST/gitpod.v1.EnvironmentAutomationService/DeleteService

ListServices

client.Environments.Automations.Services.List(ctx, params) (*ServicesPage[Service], error)

POST/gitpod.v1.EnvironmentAutomationService/ListServices

GetService

client.Environments.Automations.Services.Get(ctx, body) (*EnvironmentAutomationServiceGetResponse, error)

POST/gitpod.v1.EnvironmentAutomationService/GetService

StartService

client.Environments.Automations.Services.Start(ctx, body) (*EnvironmentAutomationServiceStartResponse, error)

POST/gitpod.v1.EnvironmentAutomationService/StartService

StopService

client.Environments.Automations.Services.Stop(ctx, body) (*EnvironmentAutomationServiceStopResponse, error)

POST/gitpod.v1.EnvironmentAutomationService/StopService

UpdateService

client.Environments.Automations.Services.Update(ctx, body) (*EnvironmentAutomationServiceUpdateResponse, error)

POST/gitpod.v1.EnvironmentAutomationService/UpdateService

ModelsExpand Collapse

type Service struct{…}

ID string

formatuuid

EnvironmentID stringOptional

formatuuid

Metadata ServiceMetadataOptional

CreatedAt TimeOptional

created_at is the time the service was created.

formatdate-time

Creator SubjectOptional

creator describes the principal who created the service.

ID stringOptional

id is the UUID of the subject

formatuuid

Principal PrincipalOptional

Principal is the principal of the subject

One of the following:

const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"

const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"

const PrincipalUser Principal = "PRINCIPAL_USER"

const PrincipalRunner Principal = "PRINCIPAL_RUNNER"

const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"

const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"

const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"

Description stringOptional

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

Name stringOptional

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 stringOptional

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 ServiceRoleOptional

role specifies the intended role or purpose of the service.

One of the following:

const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"

const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"

const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"

const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"

const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"

TriggeredBy []AutomationTriggerOptional

triggered_by is a list of trigger that start the service.

BeforeSnapshot boolOptional

Manual boolOptional

PostDevcontainerStart boolOptional

PostEnvironmentStart boolOptional

PostMachineStart boolOptional

Prebuild boolOptional

Spec ServiceSpecOptional

Commands ServiceSpecCommandsOptional

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

Ready stringOptional

Start stringOptional

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 stringOptional

DesiredPhase ServicePhaseOptional

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

One of the following:

const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"

const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"

const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"

const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"

const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"

const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"

const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"

Env []EnvironmentVariableItemOptional

env specifies environment variables for the service.

Name stringOptional

name is the environment variable name.

minLength1

Value stringOptional

value is a literal string value.

ValueFrom EnvironmentVariableSourceOptional

value_from specifies a source for the value.

SecretRef SecretRef

secret_ref references a secret by ID.

ID stringOptional

id is the UUID of the secret to reference.

formatuuid

ReadinessTimeout stringOptional

readiness_timeout is the maximum duration a service may remain in the Starting phase while readiness checks run. 0s disables the timeout.

formatregex

RunsOn RunsOnOptional

runs_on specifies the environment the service should run on.

Docker RunsOnDockerOptional

Environment []stringOptional

Image stringOptional

minLength1

Machine unknownOptional

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

Session stringOptional

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 stringOptional

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 ServiceStatusOptional

FailureMessage stringOptional

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 stringOptional

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

Output map[string, string]Optional

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

Phase ServicePhaseOptional

phase is the current phase of the service.

One of the following:

const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"

const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"

const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"

const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"

const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"

const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"

const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"

Session stringOptional

session is the current session of the service.

StatusVersion stringOptional

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.

type ServiceMetadata struct{…}

CreatedAt TimeOptional

created_at is the time the service was created.

formatdate-time

Creator SubjectOptional

creator describes the principal who created the service.

ID stringOptional

id is the UUID of the subject

formatuuid

Principal PrincipalOptional

Principal is the principal of the subject

One of the following:

const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"

const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"

const PrincipalUser Principal = "PRINCIPAL_USER"

const PrincipalRunner Principal = "PRINCIPAL_RUNNER"

const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"

const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"

const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"

Description stringOptional

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

Name stringOptional

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 stringOptional

Role ServiceRoleOptional

role specifies the intended role or purpose of the service.

One of the following:

const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"

const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"

const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"

const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"

const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"

TriggeredBy []AutomationTriggerOptional

triggered_by is a list of trigger that start the service.

BeforeSnapshot boolOptional

Manual boolOptional

PostDevcontainerStart boolOptional

PostEnvironmentStart boolOptional

PostMachineStart boolOptional

Prebuild boolOptional

type ServicePhase string

One of the following:

const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"

const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"

const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"

const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"

const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"

const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"

const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"

type ServiceRole string

One of the following:

const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"

const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"

const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"

const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"

const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"

type ServiceSpec struct{…}

Commands ServiceSpecCommandsOptional

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

Ready stringOptional

Start stringOptional

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 stringOptional

DesiredPhase ServicePhaseOptional

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

One of the following:

const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"

const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"

const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"

const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"

const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"

const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"

const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"

Env []EnvironmentVariableItemOptional

env specifies environment variables for the service.

Name stringOptional

name is the environment variable name.

minLength1

Value stringOptional

value is a literal string value.

ValueFrom EnvironmentVariableSourceOptional

value_from specifies a source for the value.

SecretRef SecretRef

secret_ref references a secret by ID.

ID stringOptional

id is the UUID of the secret to reference.

formatuuid

ReadinessTimeout stringOptional

readiness_timeout is the maximum duration a service may remain in the Starting phase while readiness checks run. 0s disables the timeout.

formatregex

RunsOn RunsOnOptional

runs_on specifies the environment the service should run on.

Docker RunsOnDockerOptional

Environment []stringOptional

Image stringOptional

minLength1

Machine unknownOptional

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

Session stringOptional

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 stringOptional

type ServiceStatus struct{…}

FailureMessage stringOptional

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 stringOptional

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

Output map[string, string]Optional

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

Phase ServicePhaseOptional

phase is the current phase of the service.

One of the following:

const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"

const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"

const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"

const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"

const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"

const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"

const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"

Session stringOptional

session is the current session of the service.

StatusVersion stringOptional

Automations

UpsertAutomationsFile

ModelsExpand Collapse

Examples

JSON Mapping

AutomationsServices

CreateService

DeleteService

ListServices

GetService

StartService

StopService

UpdateService

ModelsExpand Collapse

AutomationsTasks

CreateTask

DeleteTask

ListTasks

GetTask

StartTask

UpdateTask

AutomationsTasksExecutions

ListTaskExecutions

GetTaskExecution

StopTaskExecution