diff --git a/.stats.yml b/.stats.yml
index df3a2f0..296014e 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,2 +1,2 @@
configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-0c37e687e2a070abfe49501156af6d906ff166b6eaad779ee6c2b568515f2b7e.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gitpod%2Fgitpod-f6598ab5d6827f66b642201769e92590ea32af84ebbf24b18cc32b33dee5107e.yml
diff --git a/src/resources/accounts.ts b/src/resources/accounts.ts
index 1b70feb..6704ddc 100644
--- a/src/resources/accounts.ts
+++ b/src/resources/accounts.ts
@@ -8,22 +8,81 @@ import { RequestOptions } from '../internal/request-options';
export class Accounts extends APIResource {
/**
- * GetAccount retrieves a single Account.
+ * Gets information about the currently authenticated account.
+ *
+ * Use this method to:
+ *
+ * - Retrieve account profile information
+ * - Check organization memberships
+ * - View account settings
+ * - Get joinable organizations
+ *
+ * ### Examples
+ *
+ * - Get account details:
+ *
+ * Retrieves information about the authenticated account.
+ *
+ * ```yaml
+ * {}
+ * ```
*/
retrieve(body: AccountRetrieveParams, options?: RequestOptions): APIPromise<AccountRetrieveResponse> {
return this._client.post('/gitpod.v1.AccountService/GetAccount', { body, ...options });
}
/**
- * DeleteAccount deletes an Account. To Delete an Account, the Account must not be
- * an active member of any Organization.
+ * Deletes an account permanently.
+ *
+ * Use this method to:
+ *
+ * - Remove unused accounts
+ * - Clean up test accounts
+ * - Complete account deletion requests
+ *
+ * The account must not be an active member of any organization.
+ *
+ * ### Examples
+ *
+ * - Delete account:
+ *
+ * Permanently removes an account.
+ *
+ * ```yaml
+ * accountId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+ * ```
*/
delete(body: AccountDeleteParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.AccountService/DeleteAccount', { body, ...options });
}
/**
- * GetSSOLoginURL returns the URL to redirect the user to for SSO login.
+ * Gets the SSO login URL for a specific email domain.
+ *
+ * Use this method to:
+ *
+ * - Initiate SSO authentication
+ * - Get organization-specific login URLs
+ * - Handle SSO redirects
+ *
+ * ### Examples
+ *
+ * - Get login URL:
+ *
+ * Retrieves SSO URL for email domain.
+ *
+ * ```yaml
+ * email: "user@company.com"
+ * ```
+ *
+ * - Get URL with return path:
+ *
+ * Gets SSO URL with specific return location.
+ *
+ * ```yaml
+ * email: "user@company.com"
+ * returnTo: "https://gitpod.io/workspaces"
+ * ```
*/
getSSOLoginURL(
body: AccountGetSSOLoginURLParams,
@@ -33,8 +92,35 @@ export class Accounts extends APIResource {
}
/**
- * ListLoginProviders returns the list of login providers matching the provided
- * filters.
+ * Lists available login providers with optional filtering.
+ *
+ * Use this method to:
+ *
+ * - View supported authentication methods
+ * - Get provider-specific login URLs
+ * - Filter providers by invite
+ *
+ * ### Examples
+ *
+ * - List all providers:
+ *
+ * Shows all available login providers.
+ *
+ * ```yaml
+ * pagination:
+ * pageSize: 20
+ * ```
+ *
+ * - List for specific invite:
+ *
+ * Shows providers available for an invite.
+ *
+ * ```yaml
+ * filter:
+ * inviteId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * pagination:
+ * pageSize: 20
+ * ```
*/
listLoginProviders(
params: AccountListLoginProvidersParams,
diff --git a/src/resources/editors.ts b/src/resources/editors.ts
index ac5e5de..11232fc 100644
--- a/src/resources/editors.ts
+++ b/src/resources/editors.ts
@@ -7,14 +7,47 @@ import { RequestOptions } from '../internal/request-options';
export class Editors extends APIResource {
/**
- * GetEditor returns the editor with the given ID
+ * Gets details about a specific editor.
+ *
+ * Use this method to:
+ *
+ * - View editor information
+ * - Get editor configuration
+ *
+ * ### Examples
+ *
+ * - Get editor details:
+ *
+ * Retrieves information about a specific editor.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
retrieve(body: EditorRetrieveParams, options?: RequestOptions): APIPromise<EditorRetrieveResponse> {
return this._client.post('/gitpod.v1.EditorService/GetEditor', { body, ...options });
}
/**
- * ListEditors lists all editors available to the caller
+ * Lists all available code editors.
+ *
+ * Use this method to:
+ *
+ * - View supported editors
+ * - Get editor capabilities
+ * - Browse editor options
+ * - Check editor availability
+ *
+ * ### Examples
+ *
+ * - List editors:
+ *
+ * Shows all available editors with pagination.
+ *
+ * ```yaml
+ * pagination:
+ * pageSize: 20
+ * ```
*/
list(params: EditorListParams, options?: RequestOptions): PagePromise<EditorsEditorsPage, Editor> {
const { token, pageSize, ...body } = params;
@@ -27,7 +60,26 @@ export class Editors extends APIResource {
}
/**
- * ResolveEditorURL resolves the editor's URL for an environment
+ * Resolves the URL for accessing an editor in a specific environment.
+ *
+ * Use this method to:
+ *
+ * - Get editor access URLs
+ * - Launch editors for environments
+ * - Set up editor connections
+ * - Configure editor access
+ *
+ * ### Examples
+ *
+ * - Resolve editor URL:
+ *
+ * Gets the URL for accessing an editor in an environment.
+ *
+ * ```yaml
+ * editorId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
+ * organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+ * ```
*/
resolveURL(body: EditorResolveURLParams, options?: RequestOptions): APIPromise<EditorResolveURLResponse> {
return this._client.post('/gitpod.v1.EditorService/ResolveEditorURL', { body, ...options });
diff --git a/src/resources/environments/automations/automations.ts b/src/resources/environments/automations/automations.ts
index 61fe991..9659f33 100644
--- a/src/resources/environments/automations/automations.ts
+++ b/src/resources/environments/automations/automations.ts
@@ -48,7 +48,40 @@ export class Automations extends APIResource {
tasks: TasksAPI.Tasks = new TasksAPI.Tasks(this._client);
/**
- * UpsertAutomationsFile upserts the automations file for the given environment.
+ * Upserts the automations file for the given environment.
+ *
+ * Use this method to:
+ *
+ * - Configure environment automations
+ * - Update automation settings
+ * - Manage automation files
+ *
+ * ### Examples
+ *
+ * - Update automations file:
+ *
+ * Updates or creates the automations configuration.
+ *
+ * ```yaml
+ * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
+ * automationsFile:
+ * services:
+ * web-server:
+ * name: "Web Server"
+ * description: "Development web server"
+ * commands:
+ * start: "npm run dev"
+ * ready: "curl -s http://localhost:3000"
+ * triggeredBy:
+ * - postDevcontainerStart
+ * tasks:
+ * build:
+ * name: "Build Project"
+ * description: "Builds the project artifacts"
+ * command: "npm run build"
+ * triggeredBy:
+ * - postEnvironmentStart
+ * ```
*/
upsert(body: AutomationUpsertParams, options?: RequestOptions): APIPromise<AutomationUpsertResponse> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile', {
diff --git a/src/resources/environments/automations/services.ts b/src/resources/environments/automations/services.ts
index f45dc06..d674974 100644
--- a/src/resources/environments/automations/services.ts
+++ b/src/resources/environments/automations/services.ts
@@ -9,28 +9,154 @@ import { RequestOptions } from '../../../internal/request-options';
export class Services extends APIResource {
/**
- * CreateService
+ * 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
+ * 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
+ * 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"
+ * ```
*/
create(body: ServiceCreateParams, options?: RequestOptions): APIPromise<ServiceCreateResponse> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/CreateService', { body, ...options });
}
/**
- * GetService
+ * Gets details about a specific automation service.
+ *
+ * Use this method to:
+ *
+ * - Check service status
+ * - View service configuration
+ * - Monitor service health
+ * - Retrieve service metadata
+ *
+ * ### Examples
+ *
+ * - Get service details:
+ *
+ * Retrieves information about a specific service.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
retrieve(body: ServiceRetrieveParams, options?: RequestOptions): APIPromise<ServiceRetrieveResponse> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/GetService', { body, ...options });
}
/**
- * UpdateService
+ * Updates an automation service configuration.
+ *
+ * Use this method to:
+ *
+ * - Modify service commands
+ * - Update triggers
+ * - Change runtime settings
+ * - Adjust dependencies
+ *
+ * ### Examples
+ *
+ * - Update commands:
+ *
+ * Changes service start and ready commands.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * spec:
+ * commands:
+ * start: "npm run start:dev"
+ * ready: "curl -s http://localhost:8080"
+ * ```
+ *
+ * - Update triggers:
+ *
+ * Modifies when the service starts.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * metadata:
+ * triggeredBy:
+ * trigger:
+ * - postDevcontainerStart: true
+ * - manual: true
+ * ```
*/
update(body: ServiceUpdateParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/UpdateService', { body, ...options });
}
/**
- * ListServices
+ * 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.
+ *
+ * ```yaml
+ * filter:
+ * environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
+ * pagination:
+ * pageSize: 20
+ * ```
+ *
+ * - Filter by reference:
+ *
+ * Lists services matching specific references.
+ *
+ * ```yaml
+ * filter:
+ * references: ["web-server", "database"]
+ * pagination:
+ * pageSize: 20
+ * ```
*/
list(params: ServiceListParams, options?: RequestOptions): PagePromise<ServicesServicesPage, Service> {
const { token, pageSize, ...body } = params;
@@ -42,26 +168,84 @@ export class Services extends APIResource {
}
/**
- * DeleteService deletes a service. This call does not block until the service is
+ * Deletes an automation service. This call does not block until the service is
* deleted. If the service is not stopped it will be stopped before deletion.
+ *
+ * Use this method to:
+ *
+ * - Remove unused services
+ * - Clean up service configurations
+ * - Stop and delete services
+ *
+ * ### Examples
+ *
+ * - Delete service:
+ *
+ * Removes a service after stopping it.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * force: false
+ * ```
+ *
+ * - Force delete:
+ *
+ * Immediately removes a service.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * force: true
+ * ```
*/
delete(body: ServiceDeleteParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/DeleteService', { body, ...options });
}
/**
- * StartService starts a service. This call does not block until the service is
+ * Starts an automation service. This call does not block until the service is
* started. This call will not error if the service is already running or has been
* started.
+ *
+ * Use this method to:
+ *
+ * - Start stopped services
+ * - Resume service operations
+ * - Trigger service initialization
+ *
+ * ### Examples
+ *
+ * - Start service:
+ *
+ * Starts a previously stopped service.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
start(body: ServiceStartParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/StartService', { body, ...options });
}
/**
- * StopService stops a service. This call does not block until the service is
+ * Stops an automation service. This call does not block until the service is
* stopped. This call will not error if the service is already stopped or has been
* stopped.
+ *
+ * Use this method to:
+ *
+ * - Pause service operations
+ * - Gracefully stop services
+ * - Prepare for updates
+ *
+ * ### Examples
+ *
+ * - Stop service:
+ *
+ * Gracefully stops a running service.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
stop(body: ServiceStopParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/StopService', { body, ...options });
@@ -71,7 +255,7 @@ export class Services extends APIResource {
export type ServicesServicesPage = ServicesPage<Service>;
export interface Service {
- id?: string;
+ id: string;
environmentId?: string;
diff --git a/src/resources/environments/automations/tasks/executions.ts b/src/resources/environments/automations/tasks/executions.ts
index 964a3bd..c1de401 100644
--- a/src/resources/environments/automations/tasks/executions.ts
+++ b/src/resources/environments/automations/tasks/executions.ts
@@ -9,7 +9,24 @@ import { RequestOptions } from '../../../../internal/request-options';
export class Executions extends APIResource {
/**
- * GetTaskExecution
+ * Gets details about a specific task execution.
+ *
+ * Use this method to:
+ *
+ * - Monitor execution progress
+ * - View execution logs
+ * - Check execution status
+ * - Debug failed executions
+ *
+ * ### Examples
+ *
+ * - Get execution details:
+ *
+ * Retrieves information about a specific task execution.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
retrieve(body: ExecutionRetrieveParams, options?: RequestOptions): APIPromise<ExecutionRetrieveResponse> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/GetTaskExecution', {
@@ -19,7 +36,37 @@ export class Executions extends APIResource {
}
/**
- * ListTaskExecutions
+ * Lists executions of automation tasks.
+ *
+ * Use this method to:
+ *
+ * - View task execution history
+ * - Monitor running tasks
+ * - Track task completion status
+ *
+ * ### Examples
+ *
+ * - List all executions:
+ *
+ * Shows execution history for all tasks.
+ *
+ * ```yaml
+ * filter:
+ * environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
+ * pagination:
+ * pageSize: 20
+ * ```
+ *
+ * - Filter by phase:
+ *
+ * Lists executions in specific phases.
+ *
+ * ```yaml
+ * filter:
+ * phases: ["TASK_EXECUTION_PHASE_RUNNING", "TASK_EXECUTION_PHASE_FAILED"]
+ * pagination:
+ * pageSize: 20
+ * ```
*/
list(
params: ExecutionListParams,
@@ -34,7 +81,23 @@ export class Executions extends APIResource {
}
/**
- * StopTaskExecution
+ * Stops a running task execution.
+ *
+ * Use this method to:
+ *
+ * - Cancel long-running tasks
+ * - Stop failed executions
+ * - Interrupt task processing
+ *
+ * ### Examples
+ *
+ * - Stop execution:
+ *
+ * Stops a running task execution.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
stop(body: ExecutionStopParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/StopTaskExecution', {
diff --git a/src/resources/environments/automations/tasks/tasks.ts b/src/resources/environments/automations/tasks/tasks.ts
index a258c34..d113e00 100644
--- a/src/resources/environments/automations/tasks/tasks.ts
+++ b/src/resources/environments/automations/tasks/tasks.ts
@@ -20,28 +20,145 @@ export class Tasks extends APIResource {
executions: ExecutionsAPI.Executions = new ExecutionsAPI.Executions(this._client);
/**
- * CreateTask
+ * Creates a new automation task.
+ *
+ * Use this method to:
+ *
+ * - Define one-off or scheduled tasks
+ * - Set up build or test automation
+ * - Configure task dependencies
+ * - Specify execution environments
+ *
+ * ### Examples
+ *
+ * - Create basic task:
+ *
+ * Creates a simple build task.
+ *
+ * ```yaml
+ * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
+ * metadata:
+ * reference: "build"
+ * name: "Build Project"
+ * description: "Builds the project artifacts"
+ * triggeredBy:
+ * - postEnvironmentStart: true
+ * spec:
+ * command: "npm run build"
+ * ```
+ *
+ * - Create task with dependencies:
+ *
+ * Creates a task that depends on other services.
+ *
+ * ```yaml
+ * environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
+ * metadata:
+ * reference: "test"
+ * name: "Run Tests"
+ * description: "Runs the test suite"
+ * spec:
+ * command: "npm test"
+ * dependsOn: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"]
+ * ```
*/
create(body: TaskCreateParams, options?: RequestOptions): APIPromise<TaskCreateResponse> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/CreateTask', { body, ...options });
}
/**
- * GetTask
+ * Gets details about a specific automation task.
+ *
+ * Use this method to:
+ *
+ * - Check task configuration
+ * - View task dependencies
+ * - Monitor task status
+ *
+ * ### Examples
+ *
+ * - Get task details:
+ *
+ * Retrieves information about a specific task.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
retrieve(body: TaskRetrieveParams, options?: RequestOptions): APIPromise<TaskRetrieveResponse> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/GetTask', { body, ...options });
}
/**
- * UpdateTask
+ * Updates an automation task configuration.
+ *
+ * Use this method to:
+ *
+ * - Modify task commands
+ * - Update task triggers
+ * - Change dependencies
+ * - Adjust execution settings
+ *
+ * ### Examples
+ *
+ * - Update command:
+ *
+ * Changes the task's command.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * spec:
+ * command: "npm run test:coverage"
+ * ```
+ *
+ * - Update triggers:
+ *
+ * Modifies when the task runs.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * metadata:
+ * triggeredBy:
+ * trigger:
+ * - postEnvironmentStart: true
+ * ```
*/
update(body: TaskUpdateParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/UpdateTask', { body, ...options });
}
/**
- * ListTasks
+ * Lists automation tasks with optional filtering.
+ *
+ * Use this method to:
+ *
+ * - View all tasks in an environment
+ * - Filter tasks by reference
+ * - Monitor task status
+ *
+ * ### Examples
+ *
+ * - List environment tasks:
+ *
+ * Shows all tasks for an environment.
+ *
+ * ```yaml
+ * filter:
+ * environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
+ * pagination:
+ * pageSize: 20
+ * ```
+ *
+ * - Filter by reference:
+ *
+ * Lists tasks matching specific references.
+ *
+ * ```yaml
+ * filter:
+ * references: ["build", "test"]
+ * pagination:
+ * pageSize: 20
+ * ```
*/
list(params: TaskListParams, options?: RequestOptions): PagePromise<TasksTasksPage, Shared.Task> {
const { token, pageSize, ...body } = params;
@@ -53,15 +170,47 @@ export class Tasks extends APIResource {
}
/**
- * DeleteTask
+ * Deletes an automation task.
+ *
+ * Use this method to:
+ *
+ * - Remove unused tasks
+ * - Clean up task configurations
+ * - Delete obsolete automations
+ *
+ * ### Examples
+ *
+ * - Delete task:
+ *
+ * Removes a task and its configuration.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
delete(body: TaskDeleteParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/DeleteTask', { body, ...options });
}
/**
- * StartTask starts a task, i.e. creates a task execution. This call does not block
- * until the task is started; the task will be started asynchronously.
+ * Starts a task by creating a new task execution. This call does not block until
+ * the task is started; the task will be started asynchronously.
+ *
+ * Use this method to:
+ *
+ * - Trigger task execution
+ * - Run one-off tasks
+ * - Start scheduled tasks immediately
+ *
+ * ### Examples
+ *
+ * - Start task:
+ *
+ * Creates a new execution of a task.
+ *
+ * ```yaml
+ * id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
start(body: TaskStartParams, options?: RequestOptions): APIPromise<TaskStartResponse> {
return this._client.post('/gitpod.v1.EnvironmentAutomationService/StartTask', { body, ...options });
diff --git a/src/resources/environments/environments.ts b/src/resources/environments/environments.ts
index 270f659..b783a6d 100644
--- a/src/resources/environments/environments.ts
+++ b/src/resources/environments/environments.ts
@@ -406,7 +406,7 @@ export interface Environment {
* ID is a unique identifier of this environment. No other environment with the
* same name must be managed by this environment manager
*/
- id?: string;
+ id: string;
/**
* EnvironmentMetadata is data associated with an environment that's required for
diff --git a/src/resources/identity.ts b/src/resources/identity.ts
index 4a30913..9bfb3fd 100644
--- a/src/resources/identity.ts
+++ b/src/resources/identity.ts
@@ -7,7 +7,23 @@ import { RequestOptions } from '../internal/request-options';
export class Identity extends APIResource {
/**
- * ExchangeToken trades an exchange token for a new access token.
+ * Exchanges an exchange token for a new access token.
+ *
+ * Use this method to:
+ *
+ * - Convert exchange tokens to access tokens
+ * - Obtain new access credentials
+ * - Complete token exchange flows
+ *
+ * ### Examples
+ *
+ * - Exchange token:
+ *
+ * Trades an exchange token for an access token.
+ *
+ * ```yaml
+ * exchangeToken: "exchange-token-value"
+ * ```
*/
exchangeToken(
body: IdentityExchangeTokenParams,
@@ -17,7 +33,24 @@ export class Identity extends APIResource {
}
/**
- * GetAuthenticatedIdentity allows to retrieve the current identity.
+ * Retrieves information about the currently authenticated identity.
+ *
+ * Use this method to:
+ *
+ * - Get current user information
+ * - Check authentication status
+ * - Retrieve organization context
+ * - Validate authentication principal
+ *
+ * ### Examples
+ *
+ * - Get current identity:
+ *
+ * Retrieves details about the authenticated user.
+ *
+ * ```yaml
+ * {}
+ * ```
*/
getAuthenticatedIdentity(
body: IdentityGetAuthenticatedIdentityParams,
@@ -27,8 +60,34 @@ export class Identity extends APIResource {
}
/**
- * GetIDToken returns a token that can be used to authenticate the user against the
- * other services.
+ * Gets an ID token for authenticating with other services.
+ *
+ * Use this method to:
+ *
+ * - Obtain authentication tokens for service-to-service calls
+ * - Access protected resources
+ * - Generate scoped access tokens
+ *
+ * ### Examples
+ *
+ * - Get token for single service:
+ *
+ * Retrieves a token for authenticating with one service.
+ *
+ * ```yaml
+ * audience:
+ * - "https://api.gitpod.io"
+ * ```
+ *
+ * - Get token for multiple services:
+ *
+ * Retrieves a token valid for multiple services.
+ *
+ * ```yaml
+ * audience:
+ * - "https://api.gitpod.io"
+ * - "https://ws.gitpod.io"
+ * ```
*/
getIDToken(
body: IdentityGetIDTokenParams,
diff --git a/src/resources/runners/runners.ts b/src/resources/runners/runners.ts
index b5b446f..fba3eb3 100644
--- a/src/resources/runners/runners.ts
+++ b/src/resources/runners/runners.ts
@@ -348,7 +348,8 @@ export interface Runner {
export type RunnerCapability =
| 'RUNNER_CAPABILITY_UNSPECIFIED'
- | 'RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS';
+ | 'RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS'
+ | 'RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY';
export interface RunnerConfiguration {
/**
@@ -579,7 +580,71 @@ export interface RunnerCheckAuthenticationForHostResponse {
patSupported?: boolean;
+ /**
+ * scm_id is the unique identifier of the SCM provider
+ */
scmId?: string;
+
+ /**
+ * scm_name is the human-readable name of the SCM provider (e.g., "GitHub",
+ * "GitLab")
+ */
+ scmName?: string;
+
+ /**
+ * supports_oauth2 indicates that the host supports OAuth2 authentication
+ */
+ supportsOauth2?: RunnerCheckAuthenticationForHostResponse.SupportsOauth2;
+
+ /**
+ * supports_pat indicates that the host supports Personal Access Token
+ * authentication
+ */
+ supportsPat?: RunnerCheckAuthenticationForHostResponse.SupportsPat;
+}
+
+export namespace RunnerCheckAuthenticationForHostResponse {
+ /**
+ * supports_oauth2 indicates that the host supports OAuth2 authentication
+ */
+ export interface SupportsOauth2 {
+ /**
+ * auth_url is the URL where users can authenticate
+ */
+ authUrl?: string;
+
+ /**
+ * docs_url is the URL to the documentation explaining this authentication method
+ */
+ docsUrl?: string;
+ }
+
+ /**
+ * supports_pat indicates that the host supports Personal Access Token
+ * authentication
+ */
+ export interface SupportsPat {
+ /**
+ * create_url is the URL where users can create a new Personal Access Token
+ */
+ createUrl?: string;
+
+ /**
+ * docs_url is the URL to the documentation explaining PAT usage for this host
+ */
+ docsUrl?: string;
+
+ /**
+ * example is an example of a Personal Access Token
+ */
+ example?: string;
+
+ /**
+ * required_scopes is the list of permissions required for the Personal Access
+ * Token
+ */
+ requiredScopes?: Array<string>;
+ }
}
export interface RunnerCreateRunnerTokenResponse {
diff --git a/src/resources/secrets.ts b/src/resources/secrets.ts
index 38d9729..f7473fe 100644
--- a/src/resources/secrets.ts
+++ b/src/resources/secrets.ts
@@ -8,14 +8,74 @@ import { RequestOptions } from '../internal/request-options';
export class Secrets extends APIResource {
/**
- * CreateSecret creates a new secret.
+ * Creates a new secret for a project.
+ *
+ * Use this method to:
+ *
+ * - Store sensitive configuration values
+ * - Set up environment variables
+ * - Configure registry authentication
+ * - Add file-based secrets
+ *
+ * ### Examples
+ *
+ * - Create environment variable:
+ *
+ * Creates a secret that will be available as an environment variable.
+ *
+ * ```yaml
+ * name: "DATABASE_URL"
+ * projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+ * value: "postgresql://user:pass@localhost:5432/db"
+ * environmentVariable: true
+ * ```
+ *
+ * - Create file secret:
+ *
+ * Creates a secret that will be mounted as a file.
+ *
+ * ```yaml
+ * name: "SSH_KEY"
+ * projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+ * value: "-----BEGIN RSA PRIVATE KEY-----\n..."
+ * filePath: "/home/gitpod/.ssh/id_rsa"
+ * ```
+ *
+ * - Create registry auth:
+ *
+ * Creates credentials for private container registry.
+ *
+ * ```yaml
+ * name: "DOCKER_AUTH"
+ * projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
+ * value: "username:password"
+ * containerRegistryBasicAuthHost: "https://registry.example.com"
+ * ```
*/
create(body: SecretCreateParams, options?: RequestOptions): APIPromise<SecretCreateResponse> {
return this._client.post('/gitpod.v1.SecretService/CreateSecret', { body, ...options });
}
/**
- * ListSecrets lists secrets.
+ * Lists secrets with optional filtering.
+ *
+ * Use this method to:
+ *
+ * - View all project secrets
+ * - Filter secrets by project
+ *
+ * ### Examples
+ *
+ * - List project secrets:
+ *
+ * Shows all secrets for a project.
+ *
+ * ```yaml
+ * filter:
+ * projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"]
+ * pagination:
+ * pageSize: 20
+ * ```
*/
list(params: SecretListParams, options?: RequestOptions): PagePromise<SecretsSecretsPage, Secret> {
const { token, pageSize, ...body } = params;
@@ -28,22 +88,68 @@ export class Secrets extends APIResource {
}
/**
- * DeleteSecret deletes a secret.
+ * Deletes a secret permanently.
+ *
+ * Use this method to:
+ *
+ * - Remove unused secrets
+ * - Clean up old credentials
+ *
+ * ### Examples
+ *
+ * - Delete secret:
+ *
+ * Permanently removes a secret.
+ *
+ * ```yaml
+ * secretId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
delete(body: SecretDeleteParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.SecretService/DeleteSecret', { body, ...options });
}
/**
- * GetSecretValue retrieves the value of a secret Only Environments can perform
- * this operation, and only for secrets specified on the EnvironmentSpec.
+ * Gets the value of a secret. Only available to environments that are authorized
+ * to access the secret.
+ *
+ * Use this method to:
+ *
+ * - Retrieve secret values
+ * - Access credentials
+ *
+ * ### Examples
+ *
+ * - Get secret value:
+ *
+ * Retrieves the value of a specific secret.
+ *
+ * ```yaml
+ * secretId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
getValue(body: SecretGetValueParams, options?: RequestOptions): APIPromise<SecretGetValueResponse> {
return this._client.post('/gitpod.v1.SecretService/GetSecretValue', { body, ...options });
}
/**
- * UpdateSecretValue updates the value of a secret.
+ * Updates the value of an existing secret.
+ *
+ * Use this method to:
+ *
+ * - Rotate secret values
+ * - Update credentials
+ *
+ * ### Examples
+ *
+ * - Update secret value:
+ *
+ * Changes the value of an existing secret.
+ *
+ * ```yaml
+ * secretId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * value: "new-secret-value"
+ * ```
*/
updateValue(body: SecretUpdateValueParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.SecretService/UpdateSecretValue', { body, ...options });
diff --git a/src/resources/shared.ts b/src/resources/shared.ts
index 0ef958f..c70d702 100644
--- a/src/resources/shared.ts
+++ b/src/resources/shared.ts
@@ -35,7 +35,7 @@ export interface EnvironmentClass {
/**
* id is the unique identifier of the environment class
*/
- id?: string;
+ id: string;
/**
* configuration describes the configuration of the environment class
@@ -131,7 +131,7 @@ export interface Subject {
}
export interface Task {
- id?: string;
+ id: string;
/**
* dependencies specifies the IDs of the automations this task depends on.
diff --git a/src/resources/users/pats.ts b/src/resources/users/pats.ts
index dcb49b9..46dcda4 100644
--- a/src/resources/users/pats.ts
+++ b/src/resources/users/pats.ts
@@ -8,7 +8,26 @@ import { RequestOptions } from '../../internal/request-options';
export class Pats extends APIResource {
/**
- * ListPersonalAccessTokens
+ * Lists personal access tokens with optional filtering.
+ *
+ * Use this method to:
+ *
+ * - View all active tokens
+ * - Audit token usage
+ * - Manage token lifecycle
+ *
+ * ### Examples
+ *
+ * - List user tokens:
+ *
+ * Shows all tokens for specific users.
+ *
+ * ```yaml
+ * filter:
+ * userIds: ["f53d2330-3795-4c5d-a1f3-453121af9c60"]
+ * pagination:
+ * pageSize: 20
+ * ```
*/
list(
params: PatListParams,
@@ -23,14 +42,46 @@ export class Pats extends APIResource {
}
/**
- * DeletePersonalAccessToken
+ * Deletes a personal access token.
+ *
+ * Use this method to:
+ *
+ * - Revoke token access
+ * - Remove unused tokens
+ * - Rotate credentials
+ *
+ * ### Examples
+ *
+ * - Delete token:
+ *
+ * Permanently revokes a token.
+ *
+ * ```yaml
+ * personalAccessTokenId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
delete(body: PatDeleteParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.UserService/DeletePersonalAccessToken', { body, ...options });
}
/**
- * GetPersonalAccessToken
+ * Gets details about a specific personal access token.
+ *
+ * Use this method to:
+ *
+ * - View token metadata
+ * - Check token expiration
+ * - Monitor token usage
+ *
+ * ### Examples
+ *
+ * - Get token details:
+ *
+ * Retrieves information about a specific token.
+ *
+ * ```yaml
+ * personalAccessTokenId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
+ * ```
*/
get(body: PatGetParams, options?: RequestOptions): APIPromise<PatGetResponse> {
return this._client.post('/gitpod.v1.UserService/GetPersonalAccessToken', { body, ...options });
diff --git a/src/resources/users/users.ts b/src/resources/users/users.ts
index ede6988..842292e 100644
--- a/src/resources/users/users.ts
+++ b/src/resources/users/users.ts
@@ -20,7 +20,24 @@ export class Users extends APIResource {
pats: PatsAPI.Pats = new PatsAPI.Pats(this._client);
/**
- * GetAuthenticatedUser allows to retrieve the current user.
+ * Gets information about the currently authenticated user.
+ *
+ * Use this method to:
+ *
+ * - Get user profile information
+ * - Check authentication status
+ * - Retrieve user settings
+ * - Verify account details
+ *
+ * ### Examples
+ *
+ * - Get current user:
+ *
+ * Retrieves details about the authenticated user.
+ *
+ * ```yaml
+ * {}
+ * ```
*/
getAuthenticatedUser(
body: UserGetAuthenticatedUserParams,
@@ -30,7 +47,33 @@ export class Users extends APIResource {
}
/**
- * SetSuspended sets the suspended state of the user.
+ * Sets whether a user account is suspended.
+ *
+ * Use this method to:
+ *
+ * - Suspend problematic users
+ * - Reactivate suspended accounts
+ * - Manage user access
+ *
+ * ### Examples
+ *
+ * - Suspend user:
+ *
+ * Suspends a user account.
+ *
+ * ```yaml
+ * userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+ * suspended: true
+ * ```
+ *
+ * - Reactivate user:
+ *
+ * Removes suspension from a user account.
+ *
+ * ```yaml
+ * userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
+ * suspended: false
+ * ```
*/
setSuspended(body: UserSetSuspendedParams, options?: RequestOptions): APIPromise<unknown> {
return this._client.post('/gitpod.v1.UserService/SetSuspended', { body, ...options });
diff --git a/tests/api-resources/accounts.test.ts b/tests/api-resources/accounts.test.ts
index 932d80d..85aed19 100644
--- a/tests/api-resources/accounts.test.ts
+++ b/tests/api-resources/accounts.test.ts
@@ -22,7 +22,7 @@ describe('resource accounts', () => {
// skipped: tests are disabled for the time being
test.skip('delete: only required params', async () => {
- const responsePromise = client.accounts.delete({ accountId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' });
+ const responsePromise = client.accounts.delete({ accountId: 'f53d2330-3795-4c5d-a1f3-453121af9c60' });
const rawResponse = await responsePromise.asResponse();
expect(rawResponse).toBeInstanceOf(Response);
const response = await responsePromise;
@@ -34,12 +34,12 @@ describe('resource accounts', () => {
// skipped: tests are disabled for the time being
test.skip('delete: required and optional params', async () => {
- const response = await client.accounts.delete({ accountId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' });
+ const response = await client.accounts.delete({ accountId: 'f53d2330-3795-4c5d-a1f3-453121af9c60' });
});
// skipped: tests are disabled for the time being
test.skip('getSSOLoginURL: only required params', async () => {
- const responsePromise = client.accounts.getSSOLoginURL({ email: 'dev@stainlessapi.com' });
+ const responsePromise = client.accounts.getSSOLoginURL({ email: 'user@company.com' });
const rawResponse = await responsePromise.asResponse();
expect(rawResponse).toBeInstanceOf(Response);
const response = await responsePromise;
@@ -52,7 +52,7 @@ describe('resource accounts', () => {
// skipped: tests are disabled for the time being
test.skip('getSSOLoginURL: required and optional params', async () => {
const response = await client.accounts.getSSOLoginURL({
- email: 'dev@stainlessapi.com',
+ email: 'user@company.com',
returnTo: 'https://example.com',
});
});
diff --git a/tests/api-resources/editors.test.ts b/tests/api-resources/editors.test.ts
index a74c114..e3e3a7c 100644
--- a/tests/api-resources/editors.test.ts
+++ b/tests/api-resources/editors.test.ts
@@ -10,7 +10,7 @@ const client = new Gitpod({
describe('resource editors', () => {
// skipped: tests are disabled for the time being
test.skip('retrieve: only required params', async () => {
- const responsePromise = client.editors.retrieve({ id: 'id' });
+ const responsePromise = client.editors.retrieve({ id: 'd2c94c27-3b76-4a42-b88c-95a85e392c68' });
const rawResponse = await responsePromise.asResponse();
expect(rawResponse).toBeInstanceOf(Response);
const response = await responsePromise;
@@ -22,7 +22,7 @@ describe('resource editors', () => {
// skipped: tests are disabled for the time being
test.skip('retrieve: required and optional params', async () => {
- const response = await client.editors.retrieve({ id: 'id' });
+ const response = await client.editors.retrieve({ id: 'd2c94c27-3b76-4a42-b88c-95a85e392c68' });
});
// skipped: tests are disabled for the time being
@@ -40,9 +40,9 @@ describe('resource editors', () => {
// skipped: tests are disabled for the time being
test.skip('resolveURL: only required params', async () => {
const responsePromise = client.editors.resolveURL({
- editorId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
- environmentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
- organizationId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+ editorId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68',
+ environmentId: '07e03a28-65a5-4d98-b532-8ea67b188048',
+ organizationId: 'b0e12f6c-4c67-429d-a4a6-d9838b5da047',
});
const rawResponse = await responsePromise.asResponse();
expect(rawResponse).toBeInstanceOf(Response);
@@ -56,9 +56,9 @@ describe('resource editors', () => {
// skipped: tests are disabled for the time being
test.skip('resolveURL: required and optional params', async () => {
const response = await client.editors.resolveURL({
- editorId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
- environmentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
- organizationId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+ editorId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68',
+ environmentId: '07e03a28-65a5-4d98-b532-8ea67b188048',
+ organizationId: 'b0e12f6c-4c67-429d-a4a6-d9838b5da047',
});
});
});