Unary · Groups
Lists groups with optional pagination.
Use this method to:
- View all groups in an organization
- Check group memberships
- Monitor group configurations
- Audit group access
Examples
-
List all groups:
Shows all groups with pagination.
pagination: pageSize: 20 -
List with custom page size:
Shows groups with specified page size.
pagination: pageSize: 50 token: "next-page-token-from-previous-response"
Authorization
All organization members can list groups (transparency model).Endpoint
POST /api/gitpod.v1.GroupService/ListGroups
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.GroupService/ListGroups" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"pagination": {
"pageSize": 1
}
}'
import gitpod.v1.group_pb2 as group_pb2
import gitpod.v1.pagination_pb2 as pagination_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = group_pb2.ListGroupsRequest(
pagination=pagination_pb2.PaginationRequest(
page_size=1,
),
)
response = ona.services.group.list_groups(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListGroupsRequestSchema } from "@gitpod/sdk/gitpod/v1/group_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListGroupsRequestSchema, {
pagination: {
pageSize: 1,
},
});
const response = await ona.services.group.listGroups(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.ListGroupsRequest{
Pagination: &gitpodpb.PaginationRequest{
PageSize: 1,
},
})
response, err := ona.Services.Group.ListGroups(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"pagination": {
"pageSize": 1
}
}
Request
gitpod.v1.ListGroupsRequest
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationRequest | No | pagination contains the pagination options for listing groups |
filter | Filter | No | filter contains options for filtering the list of groups. |
Response
gitpod.v1.ListGroupsResponse
| Field | Type | Required | Description |
|---|---|---|---|
pagination | PaginationResponse | No | |
groups | array of Group | No |
Related types
Group
Group
gitpod.v1.Group| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Constraints: string.uuid=true. |
organizationId | string | No | Constraints: string.uuid=true. |
name | string | No | Constraints: string.max_len=80, string.min_len=3. |
systemManaged | boolean | No | system_managed indicates that this group is created by the system automatically |
createdAt | RFC 3339 timestamp | No | |
updatedAt | RFC 3339 timestamp | No | |
description | string | No | Constraints: string.max_len=255. |
memberCount | integer | No | member_count is the total number of members in this group |
directShare | boolean | No | direct_share indicates that this group is used for direct user sharing on resources. These groups are hidden from regular group listings. |
Filter
Filter
gitpod.v1.ListGroupsRequest.Filter| Field | Type | Required | Description |
|---|---|---|---|
search | string | No | search performs case-insensitive search across group name, description, and ID Constraints: string.max_len=256. |
groupIds | array of string | No | group_ids filters the response to only groups with the specified IDs Constraints: repeated.items.string.uuid=true, repeated.max_items=25. |
systemManaged | boolean | No | system_managed filters groups by their system_managed flag. When set, only groups matching this value are returned. |
directShare | boolean | No | direct_share filters groups by their direct_share flag. When set, only groups matching this value are returned. |
excludeAssignedToResource | ExcludeAssignedToResource | No | exclude_assigned_to_resource excludes groups that already have a role assignment on the specified resource. Used by share dialogs to hide groups that are already granted access. |
ExcludeAssignedToResource
ExcludeAssignedToResource
gitpod.v1.ListGroupsRequest.Filter.ExcludeAssignedToResource| Field | Type | Required | Description |
|---|---|---|---|
resourceType | ResourceType | No | Constraints: enum.defined_only=true, enum.not_in=0. |
resourceId | string | No | Constraints: string.uuid=true. |
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 |
ResourceType
ResourceType
| Value | Number | Description |
|---|---|---|
RESOURCE_TYPE_UNSPECIFIED | 0 | |
RESOURCE_TYPE_ENVIRONMENT | 1 | |
RESOURCE_TYPE_RUNNER | 2 | |
RESOURCE_TYPE_PROJECT | 3 | |
RESOURCE_TYPE_TASK | 4 | |
RESOURCE_TYPE_TASK_EXECUTION | 5 | |
RESOURCE_TYPE_SERVICE | 6 | |
RESOURCE_TYPE_ORGANIZATION | 7 | |
RESOURCE_TYPE_USER | 8 | |
RESOURCE_TYPE_ENVIRONMENT_CLASS | 9 | |
RESOURCE_TYPE_RUNNER_SCM_INTEGRATION | 10 | |
RESOURCE_TYPE_HOST_AUTHENTICATION_TOKEN | 11 | |
RESOURCE_TYPE_GROUP | 12 | |
RESOURCE_TYPE_PERSONAL_ACCESS_TOKEN | 13 | |
RESOURCE_TYPE_USER_PREFERENCE | 14 | |
RESOURCE_TYPE_SERVICE_ACCOUNT | 15 | |
RESOURCE_TYPE_SECRET | 16 | |
RESOURCE_TYPE_SSO_CONFIG | 17 | |
RESOURCE_TYPE_DOMAIN_VERIFICATION | 18 | |
RESOURCE_TYPE_AGENT_EXECUTION | 19 | |
RESOURCE_TYPE_RUNNER_LLM_INTEGRATION | 20 | |
RESOURCE_TYPE_AGENT | 21 | |
RESOURCE_TYPE_ENVIRONMENT_SESSION | 22 | |
RESOURCE_TYPE_USER_SECRET | 23 | |
RESOURCE_TYPE_ORGANIZATION_POLICY | 24 | |
RESOURCE_TYPE_ORGANIZATION_SECRET | 25 | |
RESOURCE_TYPE_PROJECT_ENVIRONMENT_CLASS | 26 | |
RESOURCE_TYPE_BILLING | 27 | |
RESOURCE_TYPE_PROMPT | 28 | |
RESOURCE_TYPE_COUPON | 29 | |
RESOURCE_TYPE_COUPON_REDEMPTION | 30 | |
RESOURCE_TYPE_ACCOUNT | 31 | |
RESOURCE_TYPE_INTEGRATION | 32 | |
RESOURCE_TYPE_WORKFLOW | 33 | |
RESOURCE_TYPE_WORKFLOW_EXECUTION | 34 | |
RESOURCE_TYPE_WORKFLOW_EXECUTION_ACTION | 35 | |
RESOURCE_TYPE_SNAPSHOT | 36 | |
RESOURCE_TYPE_PREBUILD | 37 | |
RESOURCE_TYPE_ORGANIZATION_LLM_INTEGRATION | 38 | |
RESOURCE_TYPE_CUSTOM_DOMAIN | 39 | |
RESOURCE_TYPE_ROLE_ASSIGNMENT_CHANGED | 40 | |
RESOURCE_TYPE_GROUP_MEMBERSHIP_CHANGED | 41 | |
RESOURCE_TYPE_WEBHOOK | 42 | |
RESOURCE_TYPE_SCIM_CONFIGURATION | 43 | |
RESOURCE_TYPE_SERVICE_ACCOUNT_SECRET | 44 | |
RESOURCE_TYPE_ANNOUNCEMENT_BANNER | 45 | |
RESOURCE_TYPE_SERVICE_ACCOUNT_TOKEN | 46 | |
RESOURCE_TYPE_ROLE_ASSIGNMENT | 47 | |
RESOURCE_TYPE_WARM_POOL | 48 | |
RESOURCE_TYPE_NOTIFICATION | 49 | |
RESOURCE_TYPE_SECURITY_POLICY | 50 |