> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Service

> Creates a new automation service for an environment.

`Unary` · [`Environment Automations`](/docs/api-reference/generated/environment-automation/overview)

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 theme={null}
  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 theme={null}
  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"
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.EnvironmentAutomationService/CreateService
```

Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.

## Request example

<CodeGroup>
  ```bash cURL theme={null}
  export ONA_HOST=https://app.ona.com
  export ONA_API_KEY=<your-token>

  curl --request POST \
    --url "$ONA_HOST/api/gitpod.v1.EnvironmentAutomationService/CreateService" \
    --header "Authorization: Bearer $ONA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "environmentId": "<environment-id>"
  }'
  ```

  ```python Python theme={null}
  import gitpod.v1.environment_automation_pb2 as environment_automation_pb2
  from ona_sdk import create_client_from_env

  ona = create_client_from_env()
  request = environment_automation_pb2.CreateServiceRequest(
      environment_id="<environment-id>",
  )
  response = ona.services.environment_automation.create_service(request)
  print(response)
  ```

  ```typescript TypeScript theme={null}
  import { create } from "@bufbuild/protobuf";
  import { createClientFromEnv } from "@gitpod/sdk";
  import { CreateServiceRequestSchema } from "@gitpod/sdk/gitpod/v1/environment_automation_pb";

  async function main() {
    const ona = createClientFromEnv();
    const request = create(CreateServiceRequestSchema, {
      environmentId: "<environment-id>",
    });
    const response = await ona.services.environmentAutomation.createService(request);
    console.log(response);
  }

  main().catch(console.error);
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"log"

  	"connectrpc.com/connect"
  	"github.com/gitpod-io/gitpod-sdk-go/sdk"
  	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
  )

  func main() {
  	ona, err := sdk.NewFromEnv()
  	if err != nil {
  		log.Fatal(err)
  	}

  	request := connect.NewRequest(&gitpodpb.CreateServiceRequest{
  		EnvironmentId: "<environment-id>",
  	})
  	response, err := ona.Services.EnvironmentAutomation.CreateService(context.Background(), request)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(response.Msg)
  }
  ```

  ```json Request body theme={null}
  {
    "environmentId": "<environment-id>"
  }
  ```
</CodeGroup>

## Request

`gitpod.v1.CreateServiceRequest`

| Field           | Type                                                | Required | Description                      |
| --------------- | --------------------------------------------------- | -------- | -------------------------------- |
| `environmentId` | string                                              | No       | Constraints: `string.uuid=true`. |
| `metadata`      | [ServiceMetadata](#type-gitpod-v1-service-metadata) | No       |                                  |
| `spec`          | [ServiceSpec](#type-gitpod-v1-service-spec)         | No       |                                  |

## Response

`gitpod.v1.CreateServiceResponse`

| Field     | Type                               | Required | Description                   |
| --------- | ---------------------------------- | -------- | ----------------------------- |
| `service` | [Service](#type-gitpod-v1-service) | Yes      | Constraints: `required=true`. |

## Related types

<a id="type-gitpod-v1-automation-trigger" />

<Accordion title="AutomationTrigger">
  An AutomationTrigger represents a trigger for an automation action.
  The `manual` field shows a start button in the UI for manually triggering the automation.
  The `post_machine_start` field indicates that the automation should be triggered after the machine has started, before the devcontainer is ready.
  This is used for machine-level services like security agents that need to start early.
  The `post_environment_start` field indicates that the automation should be triggered after the environment has started (devcontainer ready).
  The `post_devcontainer_start` field indicates that the automation should be triggered after the dev container has started.
  The `prebuild` field starts the automation during a prebuild of an environment. This phase does not have user secrets available.
  The `before_snapshot` field triggers the automation after all prebuild tasks complete but before the snapshot is taken.
  This is used for tasks that need to run last during prebuilds, such as IDE warmup.
  Note: The before\_snapshot trigger can only be used with tasks, not services.

  `gitpod.v1.AutomationTrigger`

  | Field                   | Type    | Required | Description |
  | ----------------------- | ------- | -------- | ----------- |
  | `manual`                | boolean | No       |             |
  | `postMachineStart`      | boolean | No       |             |
  | `postEnvironmentStart`  | boolean | No       |             |
  | `postDevcontainerStart` | boolean | No       |             |
  | `prebuild`              | boolean | No       |             |
  | `beforeSnapshot`        | boolean | No       |             |
</Accordion>

<a id="type-gitpod-v1-environment-variable-item" />

<Accordion title="EnvironmentVariableItem">
  EnvironmentVariableItem represents an environment variable that can be set
  either from a literal value or from a secret reference.

  `gitpod.v1.EnvironmentVariableItem`

  | Field       | Type                      | Required | Description                                                             |
  | ----------- | ------------------------- | -------- | ----------------------------------------------------------------------- |
  | `name`      | string                    | No       | name is the environment variable name. Constraints: `string.min_len=1`. |
  | `value`     | string                    | No       | value is a literal string value.                                        |
  | `valueFrom` | EnvironmentVariableSource | No       | value\_from specifies a source for the value.                           |
</Accordion>

<a id="type-gitpod-v1-runs-on" />

<Accordion title="RunsOn">
  `gitpod.v1.RunsOn`

  | Field     | Type    | Required | Description |
  | --------- | ------- | -------- | ----------- |
  | `docker`  | Docker  | No       |             |
  | `machine` | Machine | No       |             |
</Accordion>

<a id="type-gitpod-v1-service" />

<Accordion title="Service">
  `gitpod.v1.Service`

  | Field           | Type                                                | Required | Description                      |
  | --------------- | --------------------------------------------------- | -------- | -------------------------------- |
  | `id`            | string                                              | No       | Constraints: `string.uuid=true`. |
  | `environmentId` | string                                              | No       | Constraints: `string.uuid=true`. |
  | `metadata`      | [ServiceMetadata](#type-gitpod-v1-service-metadata) | No       |                                  |
  | `spec`          | [ServiceSpec](#type-gitpod-v1-service-spec)         | No       |                                  |
  | `status`        | [ServiceStatus](#type-gitpod-v1-service-status)     | No       |                                  |
</Accordion>

<a id="type-gitpod-v1-service-metadata" />

<Accordion title="ServiceMetadata">
  `gitpod.v1.ServiceMetadata`

  | Field         | Type                                                             | Required | Description                                                                                                                                                                                                                                                                          |
  | ------------- | ---------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | `reference`   | string                                                           | No       | 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). Constraints: `string.pattern=^[a-zA-Z0-9_-]&#123;1,128&#125;$`. |
  | `name`        | string                                                           | No       | 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. Constraints: `string.min_len=1`.                                                                     |
  | `description` | string                                                           | No       | description is a user-facing description for the service. It can be used to provide context and documentation for the service.                                                                                                                                                       |
  | `createdAt`   | RFC 3339 timestamp                                               | No       | created\_at is the time the service was created.                                                                                                                                                                                                                                     |
  | `creator`     | [Subject](#type-gitpod-v1-subject)                               | No       | creator describes the principal who created the service.                                                                                                                                                                                                                             |
  | `triggeredBy` | array of [AutomationTrigger](#type-gitpod-v1-automation-trigger) | No       | triggered\_by is a list of trigger that start the service.                                                                                                                                                                                                                           |
  | `role`        | [ServiceRole](#enum-gitpod-v1-service-role)                      | No       | role specifies the intended role or purpose of the service.                                                                                                                                                                                                                          |
</Accordion>

<a id="type-gitpod-v1-service-spec" />

<Accordion title="ServiceSpec">
  `gitpod.v1.ServiceSpec`

  | Field              | Type                                                                          | Required | Description                                                                                                                                                                                                                         |
  | ------------------ | ----------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `specVersion`      | 64-bit integer string                                                         | No       | 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. |
  | `desiredPhase`     | [ServicePhase](#enum-gitpod-v1-service-phase)                                 | No       | desired\_phase is the phase the service should be in. Used to start or stop the service. Constraints: `enum.defined_only=true`.                                                                                                     |
  | `commands`         | [Commands](#type-gitpod-v1-service-spec-commands)                             | No       | commands contains the commands to start, stop and check the readiness of the service                                                                                                                                                |
  | `session`          | string                                                                        | No       | 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.                                                                                            |
  | `runsOn`           | [RunsOn](#type-gitpod-v1-runs-on)                                             | No       | runs\_on specifies the environment the service should run on.                                                                                                                                                                       |
  | `env`              | array of [EnvironmentVariableItem](#type-gitpod-v1-environment-variable-item) | No       | env specifies environment variables for the service.                                                                                                                                                                                |
  | `readinessTimeout` | duration string                                                               | No       | readiness\_timeout is the maximum duration a service may remain in the Starting phase while readiness checks run. 0s disables the timeout. Constraints: `duration.lte.seconds=86400`.                                               |
</Accordion>

<a id="type-gitpod-v1-service-spec-commands" />

<Accordion title="Commands">
  `gitpod.v1.ServiceSpec.Commands`

  | Field   | Type   | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
  | ------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `start` | string | No       | 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. Constraints: `string.min_len=1`.                                                             |
  | `ready` | string | No       | 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.                                                                                                                                                                                                                                                    |
  | `stop`  | string | No       | 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. |
</Accordion>

<a id="type-gitpod-v1-service-status" />

<Accordion title="ServiceStatus">
  `gitpod.v1.ServiceStatus`

  | Field            | Type                                          | Required | Description                                                                                                                                                                                                                                                                                                                               |
  | ---------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `statusVersion`  | 64-bit integer string                         | No       | 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. |
  | `phase`          | [ServicePhase](#enum-gitpod-v1-service-phase) | No       | phase is the current phase of the service.                                                                                                                                                                                                                                                                                                |
  | `failureMessage` | string                                        | No       | 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                                        | No       | log\_url contains the URL at which the service logs can be accessed.                                                                                                                                                                                                                                                                      |
  | `session`        | string                                        | No       | session is the current session of the service.                                                                                                                                                                                                                                                                                            |
  | `output`         | map of string to string                       | No       | output contains the output of the service. setting an output field to empty string will unset it. Constraints: `map.keys.string.max_len=128, map.keys.string.min_len=1, map.values.string.max_len=4096, map.values.string.min_len=0`.                                                                                                     |
</Accordion>

<a id="type-gitpod-v1-subject" />

<Accordion title="Subject">
  `gitpod.v1.Subject`

  | Field       | Type                                   | Required | Description                                                                      |
  | ----------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------- |
  | `id`        | string                                 | No       | id is the UUID of the subject Constraints: `ignore=1, string.uuid=true`.         |
  | `principal` | [Principal](#enum-gitpod-v1-principal) | No       | Principal is the principal of the subject Constraints: `enum.defined_only=true`. |
</Accordion>

<a id="enum-gitpod-v1-principal" />

<Accordion title="Principal">
  | Value                       | Number | Description |
  | --------------------------- | -----: | ----------- |
  | `PRINCIPAL_UNSPECIFIED`     |      0 |             |
  | `PRINCIPAL_ACCOUNT`         |      1 |             |
  | `PRINCIPAL_USER`            |      2 |             |
  | `PRINCIPAL_RUNNER`          |      3 |             |
  | `PRINCIPAL_ENVIRONMENT`     |      4 |             |
  | `PRINCIPAL_SERVICE_ACCOUNT` |      5 |             |
  | `PRINCIPAL_RUNNER_MANAGER`  |      6 |             |
</Accordion>

<a id="enum-gitpod-v1-service-phase" />

<Accordion title="ServicePhase">
  | Value                       | Number | Description |
  | --------------------------- | -----: | ----------- |
  | `SERVICE_PHASE_UNSPECIFIED` |      0 |             |
  | `SERVICE_PHASE_STARTING`    |      1 |             |
  | `SERVICE_PHASE_RUNNING`     |      2 |             |
  | `SERVICE_PHASE_STOPPING`    |      3 |             |
  | `SERVICE_PHASE_STOPPED`     |      4 |             |
  | `SERVICE_PHASE_FAILED`      |      5 |             |
  | `SERVICE_PHASE_DELETED`     |      6 |             |
</Accordion>

<a id="enum-gitpod-v1-service-role" />

<Accordion title="ServiceRole">
  | Value                         | Number | Description |
  | ----------------------------- | -----: | ----------- |
  | `SERVICE_ROLE_UNSPECIFIED`    |      0 |             |
  | `SERVICE_ROLE_DEFAULT`        |      1 |             |
  | `SERVICE_ROLE_EDITOR`         |      2 |             |
  | `SERVICE_ROLE_AI_AGENT`       |      3 |             |
  | `SERVICE_ROLE_SECURITY_AGENT` |      4 |             |
</Accordion>