---
title: "UpdateService"
method: POST
path: "/gitpod.v1.EnvironmentAutomationService/UpdateService"
tags: ["gitpod.v1.EnvironmentAutomationService"]
---

# UpdateService

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

   ```yaml
   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.

   ```yaml
   id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
   metadata:
     triggeredBy:
       trigger:
         - postDevcontainerStart: true
         - manual: true
   ```

## Request body

- GitpodV1UpdateServiceRequest
  - `id` string, uuid
  - `metadata` GitpodV1UpdateServiceRequestServiceMetadata
    - `description` string, nullable
    - `name` string, nullable
    - `role` 'SERVICE_ROLE_UNSPECIFIED' | 'SERVICE_ROLE_DEFAULT' | 'SERVICE_ROLE_EDITOR' | 'SERVICE_ROLE_AI_AGENT' | 'SERVICE_ROLE_SECURITY_AGENT'
    - `triggeredBy` GitpodV1UpdateServiceRequestAutomationTriggerUpdate — unresolved $ref
  - `spec` GitpodV1UpdateServiceRequestServiceSpec — unresolved $ref
  - `status` GitpodV1UpdateServiceRequestServiceStatus
    - `failureMessage` string, nullable
    - `logUrl` string, nullable
    - `output` object — setting an output field to empty string will unset it.
    - `phase` 'SERVICE_PHASE_UNSPECIFIED' | 'SERVICE_PHASE_STARTING' | 'SERVICE_PHASE_RUNNING' | 'SERVICE_PHASE_STOPPING' | 'SERVICE_PHASE_STOPPED' | 'SERVICE_PHASE_FAILED' | 'SERVICE_PHASE_DELETED'
    - `session` string, nullable

## Response `200`

Success

- GitpodV1UpdateServiceResponse

## Other responses

- `default` — Error

## Changes

- **2026-01-21** `2423c089f280` — 1 breaking, 2 info
  - removed `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5` from the `metadata/triggeredBy/trigger/items/` request property `oneOf` list
  - added the new optional request property `metadata/triggeredBy/trigger/items/beforeSnapshot`
  - added `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5, subschema #6` to the `metadata/triggeredBy/trigger/items/` request property `oneOf` list
- **2025-12-15** `d62ef4b9187c` — 2 breaking, 7 info
  - removed `subschema #1` from the `spec/runsOn` request property `oneOf` list
  - removed `subschema #1, subschema #2, subschema #3` from the `metadata/triggeredBy/trigger/items/` request property `oneOf` list
  - added the new optional request property `metadata/role`
  - added the new optional request property `metadata/triggeredBy/trigger/items/postMachineStart`
  - …5 more
- **2025-06-10** `ca9a49ac7fbb` — 1 info
  - added the new optional request property `status/output`
- **2025-02-21** `3655d5ad0ac3` — 3 breaking, 3 warning, 9 info
  - the `metadata` request property type/format changed from ``/`` to `object`/``
  - the `spec` request property type/format changed from ``/`` to `object`/``
  - the `status` request property type/format changed from ``/`` to `object`/``
  - removed `#/components/schemas/gitpod.v1.UpdateServiceRequest.ServiceMetadata` from the `metadata` request property `allOf` list
  - …11 more
- …earlier changes not shown

[Full history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.EnvironmentAutomationService/UpdateService/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/b97dcde84128/schema)