--- 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 - `commands` GitpodV1ServiceSpecCommands - `ready` 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` 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. - `stop` 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` 'SERVICE_PHASE_UNSPECIFIED' | 'SERVICE_PHASE_STARTING' | 'SERVICE_PHASE_RUNNING' | 'SERVICE_PHASE_STOPPING' | 'SERVICE_PHASE_STOPPED' | 'SERVICE_PHASE_FAILED' | 'SERVICE_PHASE_DELETED' - `runsOn` GitpodV1RunsOn - `docker` GitpodV1RunsOnDocker, required - `environment` string[] - `image` string - `session` 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` 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. ## Response `200` Success - GitpodV1CreateServiceResponse - `service` GitpodV1Service, required - `environmentId` string, uuid - `id` string, uuid, required - `metadata` GitpodV1ServiceMetadata — unresolved $ref - `spec` GitpodV1ServiceSpec - `commands` GitpodV1ServiceSpecCommands - `ready` 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` 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. - `stop` 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` 'SERVICE_PHASE_UNSPECIFIED' | 'SERVICE_PHASE_STARTING' | 'SERVICE_PHASE_RUNNING' | 'SERVICE_PHASE_STOPPING' | 'SERVICE_PHASE_STOPPED' | 'SERVICE_PHASE_FAILED' | 'SERVICE_PHASE_DELETED' - `runsOn` GitpodV1RunsOn - `docker` GitpodV1RunsOnDocker, required - `environment` string[] - `image` string - `session` 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` 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` 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. - `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 - **2025-02-21** `3655d5ad0ac3` — 3 breaking, 2 warning, 17 info - the `metadata` request property type/format changed from ``/`` to `object`/`` - the `spec` request property type/format changed from ``/`` to `object`/`` - the `service` response's property type/format changed from ``/`` to `object`/`` for status `200` - removed `#/components/schemas/gitpod.v1.ServiceMetadata` from the `metadata` request property `allOf` list - …18 more - **2025-02-18** `cd6a05ae99d2` — 1 warning - removed the optional property `detail` from the response with the `default` status - **2025-02-18** `bef0e79f204c` — 1 info - the response property `service` became required for the status `200` - **2025-02-18** `f6598ab5d682` — 1 info - the response property `service/allOf[subschema #1: Service]/id` became required for the status `200` [Change 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/3655d5ad0ac3/schema)