Unary · Environments
Lists all environments matching the specified criteria.
Use this method to find and monitor environments across your organization.
Results are ordered by creation time with newest environments first.
Examples
-
List running environments for a project:
Retrieves all running environments for a specific project with pagination.
filter: statusPhases: ["ENVIRONMENT_PHASE_RUNNING"] projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] pagination: pageSize: 10 -
List all environments for a specific runner:
Filters environments by runner ID and creator ID.
filter: runnerIds: ["e6aa9c54-89d3-42c1-ac31-bd8d8f1concentrate"] creatorIds: ["f53d2330-3795-4c5d-a1f3-453121af9c60"] -
List stopped and deleted environments:
Retrieves all environments in stopped or deleted state.
filter: statusPhases: ["ENVIRONMENT_PHASE_STOPPED", "ENVIRONMENT_PHASE_DELETED"]
Endpoint
POST /api/gitpod.v1.EnvironmentService/ListEnvironments
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.EnvironmentService/ListEnvironments" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"pagination": {
"pageSize": 1
}
}'
import gitpod.v1.environment_pb2 as environment_pb2
import gitpod.v1.pagination_pb2 as pagination_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = environment_pb2.ListEnvironmentsRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.environment.list_environments(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListEnvironmentsRequestSchema } from "@gitpod/sdk/gitpod/v1/environment_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListEnvironmentsRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.environment.listEnvironments(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.ListEnvironmentsRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.Environment.ListEnvironments(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"pagination": {
"pageSize": 1
}
}
Request
gitpod.v1.ListEnvironmentsRequest
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationRequest | No | pagination contains the pagination options for listing environments |
filter | Filter | No | |
count | CountRequest | No | count controls whether the response includes a bounded total count. |
sort | Sort | No | sort specifies the order of results. When unspecified, environments are sorted by ID descending. |
Response
gitpod.v1.ListEnvironmentsResponse
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationResponse | No | pagination contains the pagination options for listing environments |
environments | array of Environment | No | environments are the environments that matched the query |
count | CountResponse | No | count is the bounded total count of matching environments, present only when requested via CountRequest.include on the first page. |
Related types
CountRequest
CountRequest
CountRequest controls whether the response should include a bounded
count of matching records.
gitpod.v1.CountRequest| Field | Type | Required | Description |
|---|---|---|---|
include | boolean | No | When true, the first page of results will include a CountResponse with the bounded total. Subsequent pages (requests with a pagination token) will not contain the count. |
CountResponse
CountResponse
CountResponse represents a bounded count of matching records.
When the actual count exceeds the counting limit, value is capped and
relation is set to GREATER_THAN_OR_EQUAL.
gitpod.v1.CountResponse| Field | Type | Required | Description |
|---|---|---|---|
value | integer | No | The count of matching records, capped at the server’s counting limit. |
relation | CountResponseRelation | No | Indicates whether value is the exact total or a lower bound. |
Environment
Environment
gitpod.v1.Environment| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager |
metadata | EnvironmentMetadata | No | Metadata is data associated with this environment that’s required for other parts of Gitpod to function |
spec | EnvironmentSpec | No | Spec is the configuration of the environment that’s required for the runner to start the environment |
status | EnvironmentStatus | No | Status is the current status of the environment |
EnvironmentMetadata
EnvironmentMetadata
EnvironmentMetadata is data associated with an environment that’s required for
other parts of the system to function
gitpod.v1.EnvironmentMetadata| Field | Type | Required | Description |
|---|---|---|---|
organizationId | string | No | organization_id is the ID of the organization that contains the environment Constraints: string.uuid=true. |
annotations | map of string to string | No | annotations are key/value pairs that gets attached to the environment. |
name | string | No | name is the name of the environment as specified by the user Constraints: string.max_len=80. |
creator | Subject | No | creator is the identity of the creator of the environment |
originalContextUrl | string | No | original_context_url is the normalized URL from which the environment was created |
createdAt | RFC 3339 timestamp | No | Time when the Environment was created. |
projectId | string | No | If the Environment was started from a project, the project_id will reference the project. |
runnerId | string | No | Runner is the ID of the runner that runs this environment. |
lastStartedAt | RFC 3339 timestamp | No | Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). |
archivedAt | RFC 3339 timestamp | No | Time when the Environment was archived. If not set, the environment is not archived. |
role | EnvironmentRole | No | role is the role of the environment |
prebuildId | string | No | prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. Constraints: string.uuid=true. |
lockdownAt | RFC 3339 timestamp | No | lockdown_at is the time at which the environment becomes locked down due to the organization’s maximum environment lifetime policy. Nil when no lifetime policy applies. |
sessionId | string | No | session_id is the ID of the session this environment belongs to. |
EnvironmentSpec
EnvironmentSpec
EnvironmentSpec specifies the configuration of an environment for an environment
start
gitpod.v1.EnvironmentSpec| 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 | EnvironmentPhase | No | Phase is the desired phase of the environment |
machine | Machine | No | machine is the machine spec of the environment |
content | Content | No | content is the content spec of the environment |
secrets | array of Secret | No | secrets are confidential data that is mounted into the environment |
ports | array of EnvironmentPort | No | ports is the set of ports which ought to be exposed to your network |
timeout | Timeout | No | Timeout configures the environment timeout |
admission | AdmissionLevel | No | admission controlls who can access the environment and its ports. |
devcontainer | DevContainer | No | devcontainer is the devcontainer spec of the environment |
sshPublicKeys | array of SSHPublicKey | No | ssh_public_keys are the public keys used to ssh into the environment |
automationsFile | AutomationsFile | No | automations_file is the automations file spec of the environment |
workflowActionId | string | No | workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. Constraints: string.uuid=true. |
kernelControlsConfig | KernelControlsConfig | No | kernel_controls_config configures kernel-level controls for this environment |
securityPolicyId | string | No | security_policy_id references the security policy used for this environment. If empty, the environment has no security policy. Constraints: ignore=1, string.uuid=true. |
EnvironmentStatus
EnvironmentStatus
EnvironmentStatus describes an environment status
gitpod.v1.EnvironmentStatus| Field | Type | Required | Description |
|---|---|---|---|
statusVersion | 64-bit integer string | No | version of the status update. Environment 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. |
runnerAck | RunnerACK | No | runner_ack contains the acknowledgement from the runner that is has received the environment spec. |
phase | EnvironmentPhase | No | the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle |
failureMessage | array of string | No | failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. |
environmentUrls | EnvironmentURLs | No | environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. |
machine | Machine | No | machine contains the status of the environment machine |
secrets | array of Secret | No | secrets contains the status of the environment secrets |
content | Content | No | content contains the status of the environment content. |
devcontainer | DevContainer | No | devcontainer contains the status of the devcontainer. |
sshPublicKeys | array of SSHPublicKey | No | ssh_public_keys contains the status of the environment ssh public keys |
warningMessage | array of string | No | warning_message contains warnings, e.g. when the environment is present but not in the expected state. |
automationsFile | AutomationsFile | No | automations_file contains the status of the automations file. |
activitySignal | EnvironmentActivitySignal | No | activity_signal is the last activity signal for the environment. |
Filter
Filter
gitpod.v1.ListEnvironmentsRequest.Filter| Field | Type | Required | Description |
|---|---|---|---|
runnerIds | array of string | No | runner_ids filters the response to only Environments running on these Runner IDs Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
statusPhases | array of EnvironmentPhase | No | actual_phases is a list of phases the environment must be in for it to be returned in the API call Constraints: repeated.max_items=25, repeated.min_items=0. |
creatorIds | array of string | No | creator_ids filters the response to only Environments created by specified members Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
projectIds | array of string | No | project_ids filters the response to only Environments associated with the specified projects Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
runnerKinds | array of RunnerKind | No | runner_kinds filters the response to only Environments running on these Runner Kinds Constraints: repeated.items.enum.defined_only=true, repeated.max_items=25, repeated.min_items=0. |
archivalStatus | ArchivalStatus | No | archival_status filters the response based on environment archive status Constraints: enum.defined_only=true. |
createdBefore | RFC 3339 timestamp | No | created_before filters environments created before this timestamp |
roles | array of EnvironmentRole | No | roles filters the response to only Environments with the specified roles Constraints: repeated.items.enum.defined_only=true, repeated.max_items=25, repeated.min_items=0. |
lockdownBefore | RFC 3339 timestamp | No | lockdown_before filters environments whose lockdown_at is before this timestamp. Only environments with lockdown_at set are matched. |
search | string | No | search performs case-insensitive search across environment ID, name, repository URL, and branch Constraints: string.max_len=256, string.min_len=0. |
sessionIds | array of string | No | session_ids filters the response to only environments belonging to the specified sessions Constraints: repeated.items.string.uuid=true, repeated.max_items=25, repeated.min_items=0. |
Sort
Sort
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 |
AdmissionLevel
AdmissionLevel
Admission level describes who can access an environment instance and its ports.
| Value | Number | Description |
|---|---|---|
ADMISSION_LEVEL_UNSPECIFIED | 0 | |
ADMISSION_LEVEL_OWNER_ONLY | 1 | Deprecated. ADMISSION_LEVEL_OWNER_ONLY means the environment can only be accessed by the creator. Deprecated: Use ADMISSION_LEVEL_CREATOR_ONLY instead. |
ADMISSION_LEVEL_EVERYONE | 2 | ADMISSION_LEVEL_EVERYONE means the environment (including ports) can be accessed by everyone. |
ADMISSION_LEVEL_ORGANIZATION | 3 | ADMISSION_LEVEL_ORGANIZATION means the environment (including ports) can be accessed by all members of the organization. |
ADMISSION_LEVEL_CREATOR_ONLY | 4 | ADMISSION_LEVEL_CREATOR_ONLY means the environment (including ports) can only be accessed by the user who created the environment. |
CountResponseRelation
CountResponseRelation
| Value | Number | Description |
|---|---|---|
COUNT_RESPONSE_RELATION_UNSPECIFIED | 0 | |
COUNT_RESPONSE_RELATION_EQ | 1 | The count is equal to the number of matching records. |
COUNT_RESPONSE_RELATION_GTE | 2 | The actual number of matching records is greater than or equal to the value. |
EnvironmentPhase
EnvironmentPhase
| Value | Number | Description |
|---|---|---|
ENVIRONMENT_PHASE_UNSPECIFIED | 0 | Unknown indicates an issue within the environment manager in that it cannot determine the actual phase of an environment. This phase is usually accompanied by an error. |
ENVIRONMENT_PHASE_CREATING | 10 | Creating means that the environment is first created. We organise the SCM credentials, parse context URL if need be, and allocate the unit of compute. |
ENVIRONMENT_PHASE_STARTING | 20 | Starting means that the environment is currently being started. This includes starting the unit of compute (machine), resolving secrets, setting up the Git config, initiaing the content, and starting the devcontainer. |
ENVIRONMENT_PHASE_RUNNING | 40 | Running means the environment is able to actively perform work, either by serving a user through Theia, or as a headless environment. |
ENVIRONMENT_PHASE_UPDATING | 45 | Updating means the environment is currently being updated. This includes content updates, devcontainer updates, secret updates and SSH public key updates. This phase implies that the environment is running. |
ENVIRONMENT_PHASE_STOPPING | 50 | Stopping means that the environment is currently shutting down. It could go to stopped every moment. |
ENVIRONMENT_PHASE_STOPPED | 60 | Stopped means the environment ended regularly because it was shut down. |
ENVIRONMENT_PHASE_DELETING | 70 | Deleting means the environment is currently being deleted. It could go to deleted any moment. This phase implies that the environment is stopped. |
ENVIRONMENT_PHASE_DELETED | 80 | Deleted means the environment was deleted and cannot be started again. This phase implies that the environment is stopped. |
EnvironmentRole
EnvironmentRole
EnvironmentRole represents the role of an environment
| Value | Number | Description |
|---|---|---|
ENVIRONMENT_ROLE_UNSPECIFIED | 0 | |
ENVIRONMENT_ROLE_DEFAULT | 1 | Default role for environments |
ENVIRONMENT_ROLE_PREBUILD | 2 | Prebuild role for environments that are prebuilds |
ENVIRONMENT_ROLE_WORKFLOW | 3 | Workflow role for environments that are part of a workflow |
ArchivalStatus
ArchivalStatus
| Value | Number | Description |
|---|---|---|
ARCHIVAL_STATUS_UNSPECIFIED | 0 | |
ARCHIVAL_STATUS_ACTIVE | 1 | |
ARCHIVAL_STATUS_ARCHIVED | 2 | |
ARCHIVAL_STATUS_ALL | 3 |
SortField
SortField
| Value | Number | Description |
|---|---|---|
SORT_FIELD_UNSPECIFIED | 0 | |
SORT_FIELD_ID | 1 | Sort by environment ID. |
SORT_FIELD_ARCHIVED_AT | 2 | Sort by the time the environment was archived. |
RunnerKind
RunnerKind
RunnerKind represents the kind of a runner
| Value | Number | Description |
|---|---|---|
RUNNER_KIND_UNSPECIFIED | 0 | Default zero value. Do not set explicitly. |
RUNNER_KIND_LOCAL | 1 | Deprecated. Deprecated: Local runners are no longer supported. Use RUNNER_PROVIDER_AWS_EC2 or RUNNER_PROVIDER_GCP instead. |
RUNNER_KIND_REMOTE | 2 | The runner is a remote runner |
RUNNER_KIND_LOCAL_CONFIGURATION | 3 | The runner is a system-managed runner that holds shared configuration for local runners. Every organization automatically has one of these runners, and it cannot be deleted nor can new runners of this kind be created. Organization admins can update this runner to change the shared configuration, including: - SCM Integrations. All local runners will use these integrations. - DesiredPhase. Can be set to STOPPED to disable all local runners. This runner cannot be used to run environments. |
SortOrder
SortOrder
| Value | Number | Description |
|---|---|---|
SORT_ORDER_UNSPECIFIED | 0 | |
SORT_ORDER_ASC | 1 | |
SORT_ORDER_DESC | 2 |