Create Service

Unary · Environment Automations 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"

Endpoint

POST /api/gitpod.v1.EnvironmentAutomationService/CreateService

Send a Bearer token as described in Authentication. If your organization uses a custom management-plane domain, replace https://app.ona.com with that domain.

Request example

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>"
}'

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)

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);

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)
}

{
  "environmentId": "<environment-id>"
}

Request

gitpod.v1.CreateServiceRequest

Field	Type	Required	Description
`environmentId`	string	No	Constraints: `string.uuid=true`.
`metadata`	ServiceMetadata	No
`spec`	ServiceSpec	No

Response

gitpod.v1.CreateServiceResponse

Field	Type	Required	Description
`service`	Service	Yes	Constraints: `required=true`.

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
`manual`	boolean	No
`postMachineStart`	boolean	No
`postEnvironmentStart`	boolean	No
`postDevcontainerStart`	boolean	No
`prebuild`	boolean	No
`beforeSnapshot`	boolean	No

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.

RunsOn

gitpod.v1.RunsOn

Field	Type	Required	Description
`docker`	Docker	No
`machine`	Machine	No

Service

gitpod.v1.Service

Field	Type	Required	Description
`id`	string	No	Constraints: `string.uuid=true`.
`environmentId`	string	No	Constraints: `string.uuid=true`.
`metadata`	ServiceMetadata	No
`spec`	ServiceSpec	No
`status`	ServiceStatus	No

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_-]{1,128}$`.
`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	No	creator describes the principal who created the service.
`triggeredBy`	array of AutomationTrigger	No	triggered_by is a list of trigger that start the service.
`role`	ServiceRole	No	role specifies the intended role or purpose of the service.

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	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	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	No	runs_on specifies the environment the service should run on.
`env`	array of EnvironmentVariableItem	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`.

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.

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

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	No	Principal is the principal of the subject Constraints: `enum.defined_only=true`.

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

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

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

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Examples

Endpoint

Request example

Request

Response

​Examples

​Endpoint

​Request example

​Request

​Response

​Related types

Examples

Endpoint

Request example

Request

Response

Related types