Skip to content
Ona API Reference
Ona Docs
API Reference
Environments
Automations
Services

UpdateService

environments.automations.services.update(ServiceUpdateParams**kwargs) -> object
POST/gitpod.v1.EnvironmentAutomationService/UpdateService

Updates an automation service configuration.

Use this method to:

  • Modify service commands
  • Update triggers
  • Change runtime settings
  • Adjust dependencies

Examples

  • Update commands:

    Changes service start and ready commands.

    id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
spec:
  commands:
    start: "npm run start:dev"
    ready: "curl -s http://localhost:8080"

  • Update triggers:

    Modifies when the service starts.

    id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
metadata:
  triggeredBy:
    trigger:
      - postDevcontainerStart: true
      - manual: true
ParametersExpand Collapse
id: Optional[str]
formatuuid
metadata: Optional[Metadata]
description: Optional[str]
name: Optional[str]
minLength1
role: Optional[ServiceRole]
One of the following:
"SERVICE_ROLE_UNSPECIFIED"
"SERVICE_ROLE_DEFAULT"
"SERVICE_ROLE_EDITOR"
"SERVICE_ROLE_AI_AGENT"
"SERVICE_ROLE_SECURITY_AGENT"
triggered_by: Optional[MetadataTriggeredBy]
trigger: Optional[Iterable[AutomationTrigger]]
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[Spec]

Changing the spec of a service is a complex operation. The spec of a service can only be updated if the service is in a stopped state. If the service is running, it must be stopped first.

commands: Optional[SpecCommands]
ready: Optional[str]
start: Optional[str]
stop: Optional[str]
env: Optional[Iterable[EnvironmentVariableItem]]
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
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
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.

status: Optional[Status]

Service status updates are only expected from the executing environment. As a client of this API you are not expected to provide this field. Updating this field requires the environmentservice:update_status permission.

failure_message: Optional[str]
log_url: Optional[str]
output: Optional[Dict[str, str]]

setting an output field to empty string will unset it.

phase: Optional[ServicePhase]
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]
ReturnsExpand Collapse
object

UpdateService

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
service = client.environments.automations.services.update(
    id="d2c94c27-3b76-4a42-b88c-95a85e392c68",
    spec={
        "commands": {
            "ready": "curl -s http://localhost:8080",
            "start": "npm run start:dev",
        }
    },
)
print(service)
{}
Returns Examples
{}