API Reference

Environments

Automations

Services

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

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.

  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.

  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"

Body ParametersJSONExpand Collapse

environmentId: optional string

formatuuid

metadata: optional ServiceMetadata { createdAt, creator, description, 4 more }

createdAt: optional string

created_at is the time the service was created.

formatdate-time

creator: optional Subject { id, principal }

creator describes the principal who created the service.

id: optional string

id is the UUID of the subject

formatuuid

principal: optional Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description: optional string

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

name: optional string

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: optional string

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: optional ServiceRole

role specifies the intended role or purpose of the service.

One of the following:

"SERVICE_ROLE_UNSPECIFIED"

"SERVICE_ROLE_DEFAULT"

"SERVICE_ROLE_EDITOR"

"SERVICE_ROLE_AI_AGENT"

"SERVICE_ROLE_SECURITY_AGENT"

triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more }

triggered_by is a list of trigger that start the service.

beforeSnapshot: optional boolean

manual: optional boolean

postDevcontainerStart: optional boolean

postEnvironmentStart: optional boolean

postMachineStart: optional boolean

prebuild: optional boolean

spec: optional ServiceSpec { commands, desiredPhase, env, 4 more }

commands: optional object { ready, start, stop }

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

ready: optional string

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 string

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 string

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.

desiredPhase: optional ServicePhase

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

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"

env: optional array of EnvironmentVariableItem { name, value, valueFrom }

env specifies environment variables for the service.

name: optional string

name is the environment variable name.

minLength1

value: optional string

value is a literal string value.

valueFrom: optional EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id: optional string

id is the UUID of the secret to reference.

formatuuid

readinessTimeout: optional string

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

formatregex

runsOn: optional RunsOn { docker, machine }

runs_on specifies the environment the service should run on.

docker: optional object { environment, image }

environment: optional array of string

image: optional string

minLength1

machine: optional unknown

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

session: optional string

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: optional string

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.

ReturnsExpand Collapse

service: Service { id, environmentId, metadata, 2 more }

id: string

formatuuid

environmentId: optional string

formatuuid

metadata: optional ServiceMetadata { createdAt, creator, description, 4 more }

createdAt: optional string

created_at is the time the service was created.

formatdate-time

creator: optional Subject { id, principal }

creator describes the principal who created the service.

id: optional string

id is the UUID of the subject

formatuuid

principal: optional Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description: optional string

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

name: optional string

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: optional string

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: optional ServiceRole

role specifies the intended role or purpose of the service.

One of the following:

"SERVICE_ROLE_UNSPECIFIED"

"SERVICE_ROLE_DEFAULT"

"SERVICE_ROLE_EDITOR"

"SERVICE_ROLE_AI_AGENT"

"SERVICE_ROLE_SECURITY_AGENT"

triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more }

triggered_by is a list of trigger that start the service.

beforeSnapshot: optional boolean

manual: optional boolean

postDevcontainerStart: optional boolean

postEnvironmentStart: optional boolean

postMachineStart: optional boolean

prebuild: optional boolean

spec: optional ServiceSpec { commands, desiredPhase, env, 4 more }

commands: optional object { ready, start, stop }

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

ready: optional string

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 string

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 string

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.

desiredPhase: optional ServicePhase

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

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"

env: optional array of EnvironmentVariableItem { name, value, valueFrom }

env specifies environment variables for the service.

name: optional string

name is the environment variable name.

minLength1

value: optional string

value is a literal string value.

valueFrom: optional EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id: optional string

id is the UUID of the secret to reference.

formatuuid

readinessTimeout: optional string

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

formatregex

runsOn: optional RunsOn { docker, machine }

runs_on specifies the environment the service should run on.

docker: optional object { environment, image }

environment: optional array of string

image: optional string

minLength1

machine: optional unknown

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

session: optional string

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: optional string

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: optional ServiceStatus { failureMessage, logUrl, output, 3 more }

failureMessage: optional 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: optional string

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

output: optional map[string]

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

phase: optional ServicePhase

phase is the current phase of the service.

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 string

session is the current session of the service.

statusVersion: optional 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.

CreateService

HTTP

HTTP

TypeScript

Python

Go

curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/CreateService \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

200 example

{
  "service": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "metadata": {
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "description": "description",
      "name": "x",
      "reference": "reference",
      "role": "SERVICE_ROLE_UNSPECIFIED",
      "triggeredBy": [
        {
          "beforeSnapshot": true,
          "manual": true,
          "postDevcontainerStart": true,
          "postEnvironmentStart": true,
          "postMachineStart": true,
          "prebuild": true
        }
      ]
    },
    "spec": {
      "commands": {
        "ready": "ready",
        "start": "x",
        "stop": "stop"
      },
      "desiredPhase": "SERVICE_PHASE_UNSPECIFIED",
      "env": [
        {
          "name": "x",
          "value": "value",
          "valueFrom": {
            "secretRef": {
              "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
            }
          }
        }
      ],
      "readinessTimeout": "+9125115.360s",
      "runsOn": {
        "docker": {
          "environment": [
            "string"
          ],
          "image": "x"
        },
        "machine": {}
      },
      "session": "session",
      "specVersion": "specVersion"
    },
    "status": {
      "failureMessage": "failureMessage",
      "logUrl": "logUrl",
      "output": {
        "foo": "string"
      },
      "phase": "SERVICE_PHASE_UNSPECIFIED",
      "session": "session",
      "statusVersion": "statusVersion"
    }
  }
}

Returns Examples

200 example

{
  "service": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "metadata": {
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "description": "description",
      "name": "x",
      "reference": "reference",
      "role": "SERVICE_ROLE_UNSPECIFIED",
      "triggeredBy": [
        {
          "beforeSnapshot": true,
          "manual": true,
          "postDevcontainerStart": true,
          "postEnvironmentStart": true,
          "postMachineStart": true,
          "prebuild": true
        }
      ]
    },
    "spec": {
      "commands": {
        "ready": "ready",
        "start": "x",
        "stop": "stop"
      },
      "desiredPhase": "SERVICE_PHASE_UNSPECIFIED",
      "env": [
        {
          "name": "x",
          "value": "value",
          "valueFrom": {
            "secretRef": {
              "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
            }
          }
        }
      ],
      "readinessTimeout": "+9125115.360s",
      "runsOn": {
        "docker": {
          "environment": [
            "string"
          ],
          "image": "x"
        },
        "machine": {}
      },
      "session": "session",
      "specVersion": "specVersion"
    },
    "status": {
      "failureMessage": "failureMessage",
      "logUrl": "logUrl",
      "output": {
        "foo": "string"
      },
      "phase": "SERVICE_PHASE_UNSPECIFIED",
      "session": "session",
      "statusVersion": "statusVersion"
    }
  }
}