Unary · Environment Automations
Lists automation services with optional filtering.
Use this method to:
- View all services in an environment
- Filter services by reference
- Monitor service status
Examples
-
List environment services:
Shows all services for an environment.
filter: environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] pagination: pageSize: 20 -
Filter by reference:
Lists services matching specific references.
filter: references: ["web-server", "database"] pagination: pageSize: 20
Endpoint
POST /api/gitpod.v1.EnvironmentAutomationService/ListServices
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/ListServices" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"pagination": {
"pageSize": 1
}
}'
import gitpod.v1.environment_automation_pb2 as environment_automation_pb2
import gitpod.v1.pagination_pb2 as pagination_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = environment_automation_pb2.ListServicesRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.environment_automation.list_services(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListServicesRequestSchema } from "@gitpod/sdk/gitpod/v1/environment_automation_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListServicesRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.environmentAutomation.listServices(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.ListServicesRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.EnvironmentAutomation.ListServices(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"pagination": {
"pageSize": 1
}
}
Request
gitpod.v1.ListServicesRequest
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationRequest | No | pagination contains the pagination options for listing services |
filter | Filter | No | filter contains the filter options for listing services |
Response
gitpod.v1.ListServicesResponse
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationResponse | No | |
services | array of Service | No |
Related types
Filter
Filter
gitpod.v1.ListServicesRequest.Filter| Field | Type | Required | Description |
|---|---|---|---|
environmentIds | array of string | No | environment_ids filters the response to only services of these environments Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
references | array of string | No | references filters the response to only services with these references Constraints: repeated.items.string.min_len=1, repeated.max_items=25, repeated.min_items=0. |
serviceIds | array of string | No | service_ids filters the response to only services with these IDs Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
roles | array of ServiceRole | No | roles filters the response to only services with these roles Constraints: repeated.items.enum.defined_only=true, repeated.max_items=25, repeated.min_items=0. |
PaginationRequest
PaginationRequest
gitpod.v1.PaginationRequest| Field | Type | Required | Description |
|---|---|---|---|
pageSize | integer | No | Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. Constraints: int32.gte=0, int32.lte=100. |
token | string | No | Token for the next set of results that was returned as next_token of a PaginationResponse |
PaginationResponse
PaginationResponse
gitpod.v1.PaginationResponse| Field | Type | Required | Description |
|---|---|---|---|
nextToken | string | No | Token passed for retrieving the next set of results. Empty if there are no more results |
Service
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
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
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. |
ServiceStatus
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. |
ServicePhase
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
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 |