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

# CreateService

`POST /gitpod.v1.EnvironmentAutomationService/CreateService`

Creates a new automation service for an environment.

 Use this method to:
 - Set up long-running services
 - Configure service triggers
 - Define service dependencies
 - Specify runtime environments

 ### Examples

 - Create basic service:

   Creates a simple service with start command.

   ```yaml
   environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
   metadata:
     reference: "web-server"
     name: "Web Server"
     description: "Runs the development web server"
     triggeredBy:
       - postDevcontainerStart: true
   spec:
     commands:
       start: "npm run dev"
       ready: "curl -s http://localhost:3000"
   ```

 - Create Docker-based service:

   Creates a service running in a specific container.

   ```yaml
   environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
   metadata:
     reference: "redis"
     name: "Redis Server"
     description: "Redis cache service"
   spec:
     commands:
       start: "redis-server"
     runsOn:
       docker:
         image: "redis:7"
   ```

## Request body

- GitpodV1CreateServiceRequest
  - `environmentId` string, uuid
  - `metadata` GitpodV1ServiceMetadata — unresolved $ref
  - `spec` GitpodV1ServiceSpec — unresolved $ref

## Response `200`

Success

- GitpodV1CreateServiceResponse
  - `service` GitpodV1Service, required
    - `environmentId` string, uuid
    - `id` string, uuid, required
    - `metadata` GitpodV1ServiceMetadata — unresolved $ref
    - `spec` GitpodV1ServiceSpec — unresolved $ref
    - `status` GitpodV1ServiceStatus
      - `failureMessage` string — 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` string — log_url contains the URL at which the service logs can be accessed.
      - `output` object — output contains the output of the service. 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 — session is the current session of the service.
      - `statusVersion` string — 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.

## Other responses

- `default` — Error

## Changes

- **2026-07-30** `44d50c2ac284` — 2 breaking, 2 warning, 4 info
  - removed `subschema #1, subschema #2, subschema #3` from the `spec/runsOn` request property `oneOf` list
  - added `subschema #1, subschema #2` to the `service/spec/runsOn` response property `oneOf` list for the response status `200`
  - removed the request property `spec/runsOn/terminal`
  - removed the optional property `service/spec/runsOn/terminal` from the response with the `200` status
  - …4 more
- **2026-04-02** `dabc0ff98cd7` — 3 breaking, 5 info
  - removed the enum value `PRINCIPAL_AGENT_EXECUTION` of the request property `metadata/creator/principal`
  - removed `subschema #1, subschema #2` from the `spec/runsOn` request property `oneOf` list
  - added `subschema #1, subschema #2, subschema #3` to the `service/spec/runsOn` response property `oneOf` list for the response status `200`
  - added the new optional request property `spec/runsOn/terminal`
  - …4 more
- …earlier changes not shown

[Full history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.EnvironmentAutomationService/CreateService/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/44d50c2ac284/schema)