UpsertAutomationsFile

environments.automations.upsert() -> AutomationUpsertResponse

POST/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile

Upserts the automations file for the given environment.

Use this method to:

Configure environment automations
Update automation settings
Manage automation files

Examples

Update automations file:

Updates or creates the automations configuration.

environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
automationsFile:
  services:
    web-server:
      name: "Web Server"
      description: "Development web server"
      commands:
        start: "npm run dev"
        ready: "curl -s http://localhost:3000"
      triggeredBy:
        - postDevcontainerStart
  tasks:
    build:
      name: "Build Project"
      description: "Builds the project artifacts"
      command: "npm run build"
      triggeredBy:
        - postEnvironmentStart

ParametersExpand Collapse

automations_file: Optional[AutomationsFileParam]

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

readiness_timeout: Optional[str]

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: 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"

environment_id: Optional[str]

formatuuid

ReturnsExpand Collapse

class AutomationUpsertResponse: …

updated_service_ids: Optional[List[str]]

updated_task_ids: Optional[List[str]]

UpsertAutomationsFile

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
response = client.environments.automations.upsert(
    automations_file={
        "services": {
            "web-server": {
                "commands": {
                    "ready": "curl -s http://localhost:3000",
                    "start": "npm run dev",
                },
                "description": "Development web server",
                "name": "Web Server",
                "triggered_by": ["postDevcontainerStart"],
            }
        },
        "tasks": {
            "build": {
                "command": "npm run build",
                "description": "Builds the project artifacts",
                "name": "Build Project",
                "triggered_by": ["postEnvironmentStart"],
            }
        },
    },
    environment_id="07e03a28-65a5-4d98-b532-8ea67b188048",
)
print(response.updated_service_ids)

{
  "updatedServiceIds": [
    "string"
  ],
  "updatedTaskIds": [
    "string"
  ]
}

Returns Examples

{
  "updatedServiceIds": [
    "string"
  ],
  "updatedTaskIds": [
    "string"
  ]
}