# Runners ## CheckAuthenticationForHost `runners.check_authentication_for_host(RunnerCheckAuthenticationForHostParams**kwargs) -> RunnerCheckAuthenticationForHostResponse` **post** `/gitpod.v1.RunnerService/CheckAuthenticationForHost` Checks if a user is authenticated for a specific host. Use this method to: - Verify authentication status - Get authentication URLs - Check PAT support ### Examples - Check authentication: Verifies authentication for a host. ```yaml host: "github.com" ``` ### Parameters - `host: Optional[str]` - `runner_id: Optional[str]` ### Returns - `class RunnerCheckAuthenticationForHostResponse: …` - `authenticated: Optional[bool]` - `authentication_url: Optional[str]` - `pat_supported: Optional[bool]` - `scm_id: Optional[str]` scm_id is the unique identifier of the SCM provider - `scm_name: Optional[str]` scm_name is the human-readable name of the SCM provider (e.g., "GitHub", "GitLab") - `supports_oauth2: Optional[SupportsOauth2]` supports_oauth2 indicates that the host supports OAuth2 authentication - `auth_url: Optional[str]` auth_url is the URL where users can authenticate - `docs_url: Optional[str]` docs_url is the URL to the documentation explaining this authentication method - `supports_pat: Optional[SupportsPat]` supports_pat indicates that the host supports Personal Access Token authentication - `create_url: Optional[str]` create_url is the URL where users can create a new Personal Access Token - `docs_url: Optional[str]` docs_url is the URL to the documentation explaining PAT usage for this host - `example: Optional[str]` example is an example of a Personal Access Token - `required_scopes: Optional[List[str]]` required_scopes is the list of permissions required for the Personal Access Token ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.check_authentication_for_host( host="github.com", ) print(response.authenticated) ``` #### Response ```json { "authenticated": true, "authenticationUrl": "authenticationUrl", "patSupported": true, "scmId": "scmId", "scmName": "scmName", "supportsOauth2": { "authUrl": "authUrl", "docsUrl": "docsUrl" }, "supportsPat": { "createUrl": "createUrl", "docsUrl": "docsUrl", "example": "example", "requiredScopes": [ "string" ] } } ``` ## CheckRepositoryAccess `runners.check_repository_access(RunnerCheckRepositoryAccessParams**kwargs) -> RunnerCheckRepositoryAccessResponse` **post** `/gitpod.v1.RunnerService/CheckRepositoryAccess` Checks if a principal has read access to a repository. Use this method to: - Validate repository access before workflow execution - Verify executor credentials for automation bindings Returns: - has_access: true if the principal can read the repository - FAILED_PRECONDITION if authentication is required - INVALID_ARGUMENT if the repository URL is invalid ### Examples - Check access: Verifies read access to a repository. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" repositoryUrl: "https://github.com/org/repo" ``` ### Parameters - `repository_url: Optional[str]` repository_url is the URL of the repository to check access for. Can be a clone URL (https://github.com/org/repo.git) or web URL (https://github.com/org/repo). - `runner_id: Optional[str]` ### Returns - `class RunnerCheckRepositoryAccessResponse: …` - `error_message: Optional[str]` error_message provides details when access check fails. Empty when has_access is true. - `has_access: Optional[bool]` has_access indicates whether the principal has read access to the repository. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.check_repository_access( repository_url="https://github.com/org/repo", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response.error_message) ``` #### Response ```json { "errorMessage": "errorMessage", "hasAccess": true } ``` ## CreateRunner `runners.create(RunnerCreateParams**kwargs) -> RunnerCreateResponse` **post** `/gitpod.v1.RunnerService/CreateRunner` Creates a new runner registration with the server. Registrations are very short-lived and must be renewed every 30 seconds. Use this method to: - Register organization runners - Set up runner configurations - Initialize runner credentials - Configure auto-updates ### Examples - Create cloud runner: Creates a new runner in AWS EC2. ```yaml name: "Production Runner" provider: RUNNER_PROVIDER_AWS_EC2 spec: desiredPhase: RUNNER_PHASE_ACTIVE configuration: region: "us-west" releaseChannel: RUNNER_RELEASE_CHANNEL_STABLE autoUpdate: true ``` - Create local runner: Creates a new local runner on Linux. ```yaml name: "Local Development Runner" provider: RUNNER_PROVIDER_LINUX_HOST spec: desiredPhase: RUNNER_PHASE_ACTIVE configuration: releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST autoUpdate: true ``` ### Parameters - `kind: Optional[RunnerKind]` The runner's kind This field is optional and here for backwards-compatibility. Use the provider field instead. If provider is set, the runner's kind will be deduced from the provider. Only one of kind and provider must be set. - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner name for humans - `provider: Optional[RunnerProvider]` The specific implementation type of the runner This field is optional for backwards compatibility but will be required in the future. When specified, kind must not be specified (will be deduced from provider) - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `runner_manager_id: Optional[str]` The runner manager id specifies the runner manager for the managed runner. This field is mandatory for managed runners, otheriwse should not be set. - `spec: Optional[RunnerSpecParam]` - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` ### Returns - `class RunnerCreateResponse: …` - `runner: Runner` - `created_at: Optional[datetime]` Time when the Runner was created. - `creator: Optional[Subject]` creator is the identity of the creator of the environment - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `kind: Optional[RunnerKind]` The runner's kind - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner's name which is shown to users - `provider: Optional[RunnerProvider]` The runner's provider - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `runner_id: Optional[str]` - `runner_manager_id: Optional[str]` The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners. - `spec: Optional[RunnerSpec]` The runner's specification - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` - `status: Optional[RunnerStatus]` The runner's status - `additional_info: Optional[List[FieldValue]]` additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. - `key: Optional[str]` - `value: Optional[str]` - `capabilities: Optional[List[RunnerCapability]]` capabilities is a list of capabilities the runner supports. - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` - `gateway_info: Optional[GatewayInfo]` gateway_info is information about the gateway to which the runner is connected. - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. - `llm_url: Optional[str]` llm_url is the URL of the LLM service to which the runner is connected. - `log_url: Optional[str]` - `message: Optional[str]` The runner's reported message which is shown to users. This message adds more context to the runner's phase. - `phase: Optional[RunnerPhase]` The runner's reported phase - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `region: Optional[str]` region is the region the runner is running in, if applicable. - `support_bundle_url: Optional[str]` support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. - `system_details: Optional[str]` - `updated_at: Optional[datetime]` Time when the status was last updated. - `version: Optional[str]` - `updated_at: Optional[datetime]` Time when the Runner was last udpated. - `access_token: Optional[str]` deprecated, will be removed. Use exchange_token instead. - `exchange_token: Optional[str]` exchange_token is a one-time use token that should be exchanged by the runner for an access token, using the IdentityService.ExchangeToken rpc. The token expires after 24 hours. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) runner = client.runners.create( name="Production Runner", provider="RUNNER_PROVIDER_AWS_EC2", spec={ "configuration": { "auto_update": True, "region": "us-west", "release_channel": "RUNNER_RELEASE_CHANNEL_STABLE", }, "desired_phase": "RUNNER_PHASE_ACTIVE", }, ) print(runner.runner) ``` #### Response ```json { "runner": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "kind": "RUNNER_KIND_UNSPECIFIED", "name": "name", "provider": "RUNNER_PROVIDER_UNSPECIFIED", "runnerId": "runnerId", "runnerManagerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "configuration": { "autoUpdate": true, "continuousProfiling": true, "devcontainerImageCacheEnabled": true, "encryptedHoneycombApiKey": "U3RhaW5sZXNzIHJvY2tz", "logLevel": "LOG_LEVEL_UNSPECIFIED", "metrics": { "enabled": true, "includeVerboseMetrics": true, "managedMetricsEnabled": true, "password": "password", "url": "url", "username": "username" }, "region": "region", "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED", "updateWindow": { "endHour": 0, "startHour": 0 } }, "desiredPhase": "RUNNER_PHASE_UNSPECIFIED", "variant": "RUNNER_VARIANT_UNSPECIFIED" }, "status": { "additionalInfo": [ { "key": "key", "value": "value" } ], "capabilities": [ "RUNNER_CAPABILITY_UNSPECIFIED" ], "gatewayInfo": { "gateway": { "name": "name", "url": "url", "region": "region" }, "latency": "+9125115.360s" }, "llmUrl": "llmUrl", "logUrl": "logUrl", "message": "message", "phase": "RUNNER_PHASE_UNSPECIFIED", "publicKey": "U3RhaW5sZXNzIHJvY2tz", "region": "region", "supportBundleUrl": "supportBundleUrl", "systemDetails": "systemDetails", "updatedAt": "2019-12-27T18:11:19.117Z", "version": "version" }, "updatedAt": "2019-12-27T18:11:19.117Z" }, "accessToken": "accessToken", "exchangeToken": "exchangeToken" } ``` ## CreateRunnerLogsToken `runners.create_logs_token(RunnerCreateLogsTokenParams**kwargs) -> RunnerCreateLogsTokenResponse` **post** `/gitpod.v1.RunnerService/CreateRunnerLogsToken` Creates an access token for runner logs and debug information. Generated tokens are valid for one hour and provide runner-specific access permissions. The token is scoped to a specific runner and can be used to access support bundles. ### Examples - Generate runner logs token: ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `runner_id: Optional[str]` runner_id specifies the runner for which the logs token should be created. +required ### Returns - `class RunnerCreateLogsTokenResponse: …` - `access_token: str` access_token is the token that can be used to access the logs and support bundle of the runner ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.create_logs_token( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response.access_token) ``` #### Response ```json { "accessToken": "accessToken" } ``` ## CreateRunnerToken `runners.create_runner_token(RunnerCreateRunnerTokenParams**kwargs) -> RunnerCreateRunnerTokenResponse` **post** `/gitpod.v1.RunnerService/CreateRunnerToken` Creates a new authentication token for a runner. Use this method to: - Generate runner credentials - Renew expired tokens - Set up runner authentication Note: This does not expire previously issued tokens. ### Examples - Create token: Creates a new token for runner authentication. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `runner_id: Optional[str]` ### Returns - `class RunnerCreateRunnerTokenResponse: …` - `access_token: Optional[str]` deprecated, will be removed. Use exchange_token instead. - `exchange_token: Optional[str]` exchange_token is a one-time use token that should be exchanged by the runner for an access token, using the IdentityService.ExchangeToken rpc. The token expires after 24 hours. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.create_runner_token( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response.access_token) ``` #### Response ```json { "accessToken": "accessToken", "exchangeToken": "exchangeToken" } ``` ## DeleteRunner `runners.delete(RunnerDeleteParams**kwargs) -> object` **post** `/gitpod.v1.RunnerService/DeleteRunner` Deletes a runner permanently. Use this method to: - Remove unused runners - Clean up runner registrations - Delete obsolete runners ### Examples - Delete runner: Permanently removes a runner. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `force: Optional[bool]` force indicates whether the runner should be deleted forcefully. When force deleting a Runner, all Environments on the runner are also force deleted and regular Runner lifecycle is not respected. Force deleting can result in data loss. - `runner_id: Optional[str]` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) runner = client.runners.delete( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(runner) ``` #### Response ```json {} ``` ## ListRunners `runners.list(RunnerListParams**kwargs) -> SyncRunnersPage[Runner]` **post** `/gitpod.v1.RunnerService/ListRunners` Lists all registered runners with optional filtering. Use this method to: - View all available runners - Filter by runner type - Monitor runner status - Check runner availability ### Examples - List all runners: Shows all runners with pagination. ```yaml pagination: pageSize: 20 ``` - Filter by provider: Lists only AWS EC2 runners. ```yaml filter: providers: ["RUNNER_PROVIDER_AWS_EC2"] pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `creator_ids: Optional[Sequence[str]]` creator_ids filters the response to only runner created by specified users - `kinds: Optional[List[RunnerKind]]` kinds filters the response to only runners of the specified kinds - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `providers: Optional[List[RunnerProvider]]` providers filters the response to only runners of the specified providers - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `pagination: Optional[Pagination]` pagination contains the pagination options for listing runners - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class Runner: …` - `created_at: Optional[datetime]` Time when the Runner was created. - `creator: Optional[Subject]` creator is the identity of the creator of the environment - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `kind: Optional[RunnerKind]` The runner's kind - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner's name which is shown to users - `provider: Optional[RunnerProvider]` The runner's provider - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `runner_id: Optional[str]` - `runner_manager_id: Optional[str]` The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners. - `spec: Optional[RunnerSpec]` The runner's specification - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` - `status: Optional[RunnerStatus]` The runner's status - `additional_info: Optional[List[FieldValue]]` additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. - `key: Optional[str]` - `value: Optional[str]` - `capabilities: Optional[List[RunnerCapability]]` capabilities is a list of capabilities the runner supports. - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` - `gateway_info: Optional[GatewayInfo]` gateway_info is information about the gateway to which the runner is connected. - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. - `llm_url: Optional[str]` llm_url is the URL of the LLM service to which the runner is connected. - `log_url: Optional[str]` - `message: Optional[str]` The runner's reported message which is shown to users. This message adds more context to the runner's phase. - `phase: Optional[RunnerPhase]` The runner's reported phase - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `region: Optional[str]` region is the region the runner is running in, if applicable. - `support_bundle_url: Optional[str]` support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. - `system_details: Optional[str]` - `updated_at: Optional[datetime]` Time when the status was last updated. - `version: Optional[str]` - `updated_at: Optional[datetime]` Time when the Runner was last udpated. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.runners.list( filter={ "providers": ["RUNNER_PROVIDER_AWS_EC2"] }, pagination={ "page_size": 20 }, ) page = page.runners[0] print(page.provider) ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "runners": [ { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "kind": "RUNNER_KIND_UNSPECIFIED", "name": "name", "provider": "RUNNER_PROVIDER_UNSPECIFIED", "runnerId": "runnerId", "runnerManagerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "configuration": { "autoUpdate": true, "continuousProfiling": true, "devcontainerImageCacheEnabled": true, "encryptedHoneycombApiKey": "U3RhaW5sZXNzIHJvY2tz", "logLevel": "LOG_LEVEL_UNSPECIFIED", "metrics": { "enabled": true, "includeVerboseMetrics": true, "managedMetricsEnabled": true, "password": "password", "url": "url", "username": "username" }, "region": "region", "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED", "updateWindow": { "endHour": 0, "startHour": 0 } }, "desiredPhase": "RUNNER_PHASE_UNSPECIFIED", "variant": "RUNNER_VARIANT_UNSPECIFIED" }, "status": { "additionalInfo": [ { "key": "key", "value": "value" } ], "capabilities": [ "RUNNER_CAPABILITY_UNSPECIFIED" ], "gatewayInfo": { "gateway": { "name": "name", "url": "url", "region": "region" }, "latency": "+9125115.360s" }, "llmUrl": "llmUrl", "logUrl": "logUrl", "message": "message", "phase": "RUNNER_PHASE_UNSPECIFIED", "publicKey": "U3RhaW5sZXNzIHJvY2tz", "region": "region", "supportBundleUrl": "supportBundleUrl", "systemDetails": "systemDetails", "updatedAt": "2019-12-27T18:11:19.117Z", "version": "version" }, "updatedAt": "2019-12-27T18:11:19.117Z" } ] } ``` ## ListSCMOrganizations `runners.list_scm_organizations(RunnerListScmOrganizationsParams**kwargs) -> RunnerListScmOrganizationsResponse` **post** `/gitpod.v1.RunnerService/ListSCMOrganizations` Lists SCM organizations the user belongs to. Use this method to: - Get all organizations for a user on a specific SCM host - Check organization admin permissions for webhook creation ### Examples - List GitHub organizations: Lists all organizations the user belongs to on GitHub. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" scmHost: "github.com" ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `runner_id: Optional[str]` - `scm_host: Optional[str]` The SCM host to list organizations from (e.g., "github.com", "gitlab.com") ### Returns - `class RunnerListScmOrganizationsResponse: …` - `organizations: Optional[List[Organization]]` List of organizations the user belongs to - `is_admin: Optional[bool]` Whether the user has admin permissions in this organization. Admin permissions typically allow creating organization-level webhooks. - `name: Optional[str]` Organization name/slug (e.g., "gitpod-io") - `url: Optional[str]` Organization URL (e.g., "https://github.com/gitpod-io") ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.list_scm_organizations( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", scm_host="github.com", ) print(response.organizations) ``` #### Response ```json { "organizations": [ { "isAdmin": true, "name": "name", "url": "url" } ] } ``` ## ParseContextURL `runners.parse_context_url(RunnerParseContextURLParams**kwargs) -> RunnerParseContextURLResponse` **post** `/gitpod.v1.RunnerService/ParseContextURL` Parses a context URL and returns the parsed result. Use this method to: - Validate context URLs - Check repository access - Verify branch existence Returns: - FAILED_PRECONDITION if authentication is required - PERMISSION_DENIED if access is not allowed - INVALID_ARGUMENT if URL is invalid - NOT_FOUND if repository/branch doesn't exist ### Examples - Parse URL: Parses and validates a context URL. ```yaml contextUrl: "https://github.com/org/repo/tree/main" ``` ### Parameters - `context_url: Optional[str]` - `runner_id: Optional[str]` ### Returns - `class RunnerParseContextURLResponse: …` - `git: Optional[Git]` - `branch: Optional[str]` - `clone_url: Optional[str]` - `commit: Optional[str]` - `host: Optional[str]` - `owner: Optional[str]` - `repo: Optional[str]` - `tag: Optional[str]` - `upstream_remote_url: Optional[str]` - `issue: Optional[Issue]` - `id: Optional[str]` id is the source system's ID of this issue, e.g. BNFRD-6100 - `title: Optional[str]` - `original_context_url: Optional[str]` - `pr: Optional[Pr]` Deprecated: Use top-level PullRequest message instead - `id: Optional[str]` - `from_branch: Optional[str]` - `title: Optional[str]` - `to_branch: Optional[str]` - `project_ids: Optional[List[str]]` project_ids is a list of projects to which the context URL belongs to. - `pull_request: Optional[PullRequest]` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: Optional[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[PullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `scm_id: Optional[str]` scm_id is the unique identifier of the SCM provider (e.g., "github", "gitlab", "bitbucket") ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.parse_context_url( context_url="https://github.com/org/repo/tree/main", ) print(response.git) ``` #### Response ```json { "git": { "branch": "branch", "cloneUrl": "cloneUrl", "commit": "commit", "host": "host", "owner": "owner", "repo": "repo", "tag": "tag", "upstreamRemoteUrl": "upstreamRemoteUrl" }, "issue": { "id": "id", "title": "title" }, "originalContextUrl": "originalContextUrl", "pr": { "id": "id", "fromBranch": "fromBranch", "title": "title", "toBranch": "toBranch" }, "projectIds": [ "string" ], "pullRequest": { "id": "id", "author": "author", "draft": true, "fromBranch": "fromBranch", "repository": { "cloneUrl": "cloneUrl", "host": "host", "name": "name", "owner": "owner" }, "state": "STATE_UNSPECIFIED", "title": "title", "toBranch": "toBranch", "url": "url" }, "scmId": "scmId" } ``` ## GetRunner `runners.retrieve(RunnerRetrieveParams**kwargs) -> RunnerRetrieveResponse` **post** `/gitpod.v1.RunnerService/GetRunner` Gets details about a specific runner. Use this method to: - Check runner status - View runner configuration - Monitor runner health - Verify runner capabilities ### Examples - Get runner details: Retrieves information about a specific runner. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `runner_id: Optional[str]` ### Returns - `class RunnerRetrieveResponse: …` - `runner: Runner` - `created_at: Optional[datetime]` Time when the Runner was created. - `creator: Optional[Subject]` creator is the identity of the creator of the environment - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `kind: Optional[RunnerKind]` The runner's kind - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner's name which is shown to users - `provider: Optional[RunnerProvider]` The runner's provider - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `runner_id: Optional[str]` - `runner_manager_id: Optional[str]` The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners. - `spec: Optional[RunnerSpec]` The runner's specification - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` - `status: Optional[RunnerStatus]` The runner's status - `additional_info: Optional[List[FieldValue]]` additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. - `key: Optional[str]` - `value: Optional[str]` - `capabilities: Optional[List[RunnerCapability]]` capabilities is a list of capabilities the runner supports. - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` - `gateway_info: Optional[GatewayInfo]` gateway_info is information about the gateway to which the runner is connected. - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. - `llm_url: Optional[str]` llm_url is the URL of the LLM service to which the runner is connected. - `log_url: Optional[str]` - `message: Optional[str]` The runner's reported message which is shown to users. This message adds more context to the runner's phase. - `phase: Optional[RunnerPhase]` The runner's reported phase - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `region: Optional[str]` region is the region the runner is running in, if applicable. - `support_bundle_url: Optional[str]` support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. - `system_details: Optional[str]` - `updated_at: Optional[datetime]` Time when the status was last updated. - `version: Optional[str]` - `updated_at: Optional[datetime]` Time when the Runner was last udpated. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) runner = client.runners.retrieve( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(runner.runner) ``` #### Response ```json { "runner": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "kind": "RUNNER_KIND_UNSPECIFIED", "name": "name", "provider": "RUNNER_PROVIDER_UNSPECIFIED", "runnerId": "runnerId", "runnerManagerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "configuration": { "autoUpdate": true, "continuousProfiling": true, "devcontainerImageCacheEnabled": true, "encryptedHoneycombApiKey": "U3RhaW5sZXNzIHJvY2tz", "logLevel": "LOG_LEVEL_UNSPECIFIED", "metrics": { "enabled": true, "includeVerboseMetrics": true, "managedMetricsEnabled": true, "password": "password", "url": "url", "username": "username" }, "region": "region", "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED", "updateWindow": { "endHour": 0, "startHour": 0 } }, "desiredPhase": "RUNNER_PHASE_UNSPECIFIED", "variant": "RUNNER_VARIANT_UNSPECIFIED" }, "status": { "additionalInfo": [ { "key": "key", "value": "value" } ], "capabilities": [ "RUNNER_CAPABILITY_UNSPECIFIED" ], "gatewayInfo": { "gateway": { "name": "name", "url": "url", "region": "region" }, "latency": "+9125115.360s" }, "llmUrl": "llmUrl", "logUrl": "logUrl", "message": "message", "phase": "RUNNER_PHASE_UNSPECIFIED", "publicKey": "U3RhaW5sZXNzIHJvY2tz", "region": "region", "supportBundleUrl": "supportBundleUrl", "systemDetails": "systemDetails", "updatedAt": "2019-12-27T18:11:19.117Z", "version": "version" }, "updatedAt": "2019-12-27T18:11:19.117Z" } } ``` ## SearchRepositories `runners.search_repositories(RunnerSearchRepositoriesParams**kwargs) -> RunnerSearchRepositoriesResponse` **post** `/gitpod.v1.RunnerService/SearchRepositories` Searches for repositories across all authenticated SCM hosts. Use this method to: - List available repositories - Search repositories by name or content - Discover repositories for environment creation Returns repositories from all authenticated SCM hosts in natural sort order. If no repositories are found, returns an empty list. ### Examples - List all repositories: Returns up to 25 repositories from all authenticated hosts. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` - Search repositories: Searches for repositories matching the query across all hosts. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" searchString: "my-project" limit: 10 ``` ### Parameters - `limit: Optional[int]` Maximum number of repositories to return. Default: 25, Maximum: 100 Deprecated: Use pagination.page_size instead - `pagination: Optional[Pagination]` Pagination parameters for repository search - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. - `runner_id: Optional[str]` - `scm_host: Optional[str]` The SCM's host to retrieve repositories from - `search_mode: Optional[SearchMode]` Search mode determines how search_string is interpreted - `"SEARCH_MODE_UNSPECIFIED"` - `"SEARCH_MODE_KEYWORD"` - `"SEARCH_MODE_NATIVE"` - `search_string: Optional[str]` Search query - interpretation depends on search_mode ### Returns - `class RunnerSearchRepositoriesResponse: …` - `last_page: Optional[int]` Deprecated: Use pagination token instead. Total pages can be extracted from token. - `pagination: Optional[Pagination]` Pagination information for the response. Token format: "NEXT_PAGE/TOTAL_PAGES/TOTAL_COUNT" (e.g., "2/40/1000"). Use -1 for unknown values (e.g., "2/-1/-1" when totals unavailable). Empty token means no more pages. - `next_token: Optional[str]` Token passed for retrieving the next set of results. Empty if there are no more results - `repositories: Optional[List[Repository]]` List of repositories matching the search criteria - `name: Optional[str]` Repository name (e.g., "my-project") - `url: Optional[str]` Repository URL (e.g., "https://github.com/owner/my-project") ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.search_repositories( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response.last_page) ``` #### Response ```json { "lastPage": 0, "pagination": { "nextToken": "nextToken" }, "repositories": [ { "name": "name", "url": "url" } ] } ``` ## UpdateRunner `runners.update(RunnerUpdateParams**kwargs) -> object` **post** `/gitpod.v1.RunnerService/UpdateRunner` Updates a runner's configuration. Use this method to: - Modify runner settings - Update release channels - Change runner status - Configure auto-update settings ### Examples - Update configuration: Changes runner settings. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" name: "Updated Runner Name" spec: configuration: releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST autoUpdate: true ``` ### Parameters - `name: Optional[str]` The runner's name which is shown to users - `runner_id: Optional[str]` runner_id specifies which runner to be updated. +required - `spec: Optional[Spec]` - `configuration: Optional[SpecConfiguration]` - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the shared devcontainer build cache is enabled for this runner. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[SpecConfigurationMetrics]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindowParam]` update_window defines the daily time window (UTC) during which auto-updates are allowed. start_hour is required. If end_hour is omitted, it defaults to start_hour + 2. Send an empty UpdateWindow (no start_hour or end_hour) to clear a custom window and allow updates at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` desired_phase can currently only be updated on local-configuration runners, to toggle whether local runners are allowed for running environments in the organization. Set to: - ACTIVE to enable local runners. - INACTIVE to disable all local runners. Existing local runners and their environments will stop, and cannot be started again until the desired_phase is set to ACTIVE. Use this carefully, as it will affect all users in the organization who use local runners. - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) runner = client.runners.update( name="Updated Runner Name", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", spec={ "configuration": { "auto_update": True, "release_channel": "RUNNER_RELEASE_CHANNEL_LATEST", } }, ) print(runner) ``` #### Response ```json {} ``` ## Domain Types ### Gateway Info - `class GatewayInfo: …` - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. ### Log Level - `Literal["LOG_LEVEL_UNSPECIFIED", "LOG_LEVEL_DEBUG", "LOG_LEVEL_INFO", 2 more]` - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` ### Metrics Configuration - `class MetricsConfiguration: …` - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector ### Runner - `class Runner: …` - `created_at: Optional[datetime]` Time when the Runner was created. - `creator: Optional[Subject]` creator is the identity of the creator of the environment - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `kind: Optional[RunnerKind]` The runner's kind - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner's name which is shown to users - `provider: Optional[RunnerProvider]` The runner's provider - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `runner_id: Optional[str]` - `runner_manager_id: Optional[str]` The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners. - `spec: Optional[RunnerSpec]` The runner's specification - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` - `status: Optional[RunnerStatus]` The runner's status - `additional_info: Optional[List[FieldValue]]` additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. - `key: Optional[str]` - `value: Optional[str]` - `capabilities: Optional[List[RunnerCapability]]` capabilities is a list of capabilities the runner supports. - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` - `gateway_info: Optional[GatewayInfo]` gateway_info is information about the gateway to which the runner is connected. - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. - `llm_url: Optional[str]` llm_url is the URL of the LLM service to which the runner is connected. - `log_url: Optional[str]` - `message: Optional[str]` The runner's reported message which is shown to users. This message adds more context to the runner's phase. - `phase: Optional[RunnerPhase]` The runner's reported phase - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `region: Optional[str]` region is the region the runner is running in, if applicable. - `support_bundle_url: Optional[str]` support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. - `system_details: Optional[str]` - `updated_at: Optional[datetime]` Time when the status was last updated. - `version: Optional[str]` - `updated_at: Optional[datetime]` Time when the Runner was last udpated. ### Runner Capability - `Literal["RUNNER_CAPABILITY_UNSPECIFIED", "RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS", "RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY", 11 more]` - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` ### Runner Configuration - `class RunnerConfiguration: …` - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required ### Runner Kind - `Literal["RUNNER_KIND_UNSPECIFIED", "RUNNER_KIND_LOCAL", "RUNNER_KIND_REMOTE", "RUNNER_KIND_LOCAL_CONFIGURATION"]` RunnerKind represents the kind of a runner - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` ### Runner Phase - `Literal["RUNNER_PHASE_UNSPECIFIED", "RUNNER_PHASE_CREATED", "RUNNER_PHASE_INACTIVE", 4 more]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` ### Runner Provider - `Literal["RUNNER_PROVIDER_UNSPECIFIED", "RUNNER_PROVIDER_AWS_EC2", "RUNNER_PROVIDER_LINUX_HOST", 4 more]` RunnerProvider identifies the specific implementation type of a runner. Each provider maps to a specific kind of runner (local or remote), as specified below for each provider. - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` ### Runner Release Channel - `Literal["RUNNER_RELEASE_CHANNEL_UNSPECIFIED", "RUNNER_RELEASE_CHANNEL_STABLE", "RUNNER_RELEASE_CHANNEL_LATEST"]` - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` ### Runner Spec - `class RunnerSpec: …` - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` ### Runner Status - `class RunnerStatus: …` RunnerStatus represents the status of a runner - `additional_info: Optional[List[FieldValue]]` additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. - `key: Optional[str]` - `value: Optional[str]` - `capabilities: Optional[List[RunnerCapability]]` capabilities is a list of capabilities the runner supports. - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` - `gateway_info: Optional[GatewayInfo]` gateway_info is information about the gateway to which the runner is connected. - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. - `llm_url: Optional[str]` llm_url is the URL of the LLM service to which the runner is connected. - `log_url: Optional[str]` - `message: Optional[str]` The runner's reported message which is shown to users. This message adds more context to the runner's phase. - `phase: Optional[RunnerPhase]` The runner's reported phase - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `region: Optional[str]` region is the region the runner is running in, if applicable. - `support_bundle_url: Optional[str]` support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. - `system_details: Optional[str]` - `updated_at: Optional[datetime]` Time when the status was last updated. - `version: Optional[str]` ### Runner Variant - `Literal["RUNNER_VARIANT_UNSPECIFIED", "RUNNER_VARIANT_STANDARD", "RUNNER_VARIANT_ENTERPRISE"]` - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` ### Search Mode - `Literal["SEARCH_MODE_UNSPECIFIED", "SEARCH_MODE_KEYWORD", "SEARCH_MODE_NATIVE"]` - `"SEARCH_MODE_UNSPECIFIED"` - `"SEARCH_MODE_KEYWORD"` - `"SEARCH_MODE_NATIVE"` ### Update Window - `class UpdateWindow: …` UpdateWindow defines a daily time window (UTC) during which auto-updates are allowed. The window must be at least 2 hours long. Overnight windows are supported (e.g., start_hour=22, end_hour=4). - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required ### Runner Check Authentication For Host Response - `class RunnerCheckAuthenticationForHostResponse: …` - `authenticated: Optional[bool]` - `authentication_url: Optional[str]` - `pat_supported: Optional[bool]` - `scm_id: Optional[str]` scm_id is the unique identifier of the SCM provider - `scm_name: Optional[str]` scm_name is the human-readable name of the SCM provider (e.g., "GitHub", "GitLab") - `supports_oauth2: Optional[SupportsOauth2]` supports_oauth2 indicates that the host supports OAuth2 authentication - `auth_url: Optional[str]` auth_url is the URL where users can authenticate - `docs_url: Optional[str]` docs_url is the URL to the documentation explaining this authentication method - `supports_pat: Optional[SupportsPat]` supports_pat indicates that the host supports Personal Access Token authentication - `create_url: Optional[str]` create_url is the URL where users can create a new Personal Access Token - `docs_url: Optional[str]` docs_url is the URL to the documentation explaining PAT usage for this host - `example: Optional[str]` example is an example of a Personal Access Token - `required_scopes: Optional[List[str]]` required_scopes is the list of permissions required for the Personal Access Token ### Runner Check Repository Access Response - `class RunnerCheckRepositoryAccessResponse: …` - `error_message: Optional[str]` error_message provides details when access check fails. Empty when has_access is true. - `has_access: Optional[bool]` has_access indicates whether the principal has read access to the repository. ### Runner Create Response - `class RunnerCreateResponse: …` - `runner: Runner` - `created_at: Optional[datetime]` Time when the Runner was created. - `creator: Optional[Subject]` creator is the identity of the creator of the environment - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `kind: Optional[RunnerKind]` The runner's kind - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner's name which is shown to users - `provider: Optional[RunnerProvider]` The runner's provider - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `runner_id: Optional[str]` - `runner_manager_id: Optional[str]` The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners. - `spec: Optional[RunnerSpec]` The runner's specification - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` - `status: Optional[RunnerStatus]` The runner's status - `additional_info: Optional[List[FieldValue]]` additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. - `key: Optional[str]` - `value: Optional[str]` - `capabilities: Optional[List[RunnerCapability]]` capabilities is a list of capabilities the runner supports. - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` - `gateway_info: Optional[GatewayInfo]` gateway_info is information about the gateway to which the runner is connected. - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. - `llm_url: Optional[str]` llm_url is the URL of the LLM service to which the runner is connected. - `log_url: Optional[str]` - `message: Optional[str]` The runner's reported message which is shown to users. This message adds more context to the runner's phase. - `phase: Optional[RunnerPhase]` The runner's reported phase - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `region: Optional[str]` region is the region the runner is running in, if applicable. - `support_bundle_url: Optional[str]` support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. - `system_details: Optional[str]` - `updated_at: Optional[datetime]` Time when the status was last updated. - `version: Optional[str]` - `updated_at: Optional[datetime]` Time when the Runner was last udpated. - `access_token: Optional[str]` deprecated, will be removed. Use exchange_token instead. - `exchange_token: Optional[str]` exchange_token is a one-time use token that should be exchanged by the runner for an access token, using the IdentityService.ExchangeToken rpc. The token expires after 24 hours. ### Runner Create Logs Token Response - `class RunnerCreateLogsTokenResponse: …` - `access_token: str` access_token is the token that can be used to access the logs and support bundle of the runner ### Runner Create Runner Token Response - `class RunnerCreateRunnerTokenResponse: …` - `access_token: Optional[str]` deprecated, will be removed. Use exchange_token instead. - `exchange_token: Optional[str]` exchange_token is a one-time use token that should be exchanged by the runner for an access token, using the IdentityService.ExchangeToken rpc. The token expires after 24 hours. ### Runner List Scm Organizations Response - `class RunnerListScmOrganizationsResponse: …` - `organizations: Optional[List[Organization]]` List of organizations the user belongs to - `is_admin: Optional[bool]` Whether the user has admin permissions in this organization. Admin permissions typically allow creating organization-level webhooks. - `name: Optional[str]` Organization name/slug (e.g., "gitpod-io") - `url: Optional[str]` Organization URL (e.g., "https://github.com/gitpod-io") ### Runner Parse Context URL Response - `class RunnerParseContextURLResponse: …` - `git: Optional[Git]` - `branch: Optional[str]` - `clone_url: Optional[str]` - `commit: Optional[str]` - `host: Optional[str]` - `owner: Optional[str]` - `repo: Optional[str]` - `tag: Optional[str]` - `upstream_remote_url: Optional[str]` - `issue: Optional[Issue]` - `id: Optional[str]` id is the source system's ID of this issue, e.g. BNFRD-6100 - `title: Optional[str]` - `original_context_url: Optional[str]` - `pr: Optional[Pr]` Deprecated: Use top-level PullRequest message instead - `id: Optional[str]` - `from_branch: Optional[str]` - `title: Optional[str]` - `to_branch: Optional[str]` - `project_ids: Optional[List[str]]` project_ids is a list of projects to which the context URL belongs to. - `pull_request: Optional[PullRequest]` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: Optional[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[PullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `scm_id: Optional[str]` scm_id is the unique identifier of the SCM provider (e.g., "github", "gitlab", "bitbucket") ### Runner Retrieve Response - `class RunnerRetrieveResponse: …` - `runner: Runner` - `created_at: Optional[datetime]` Time when the Runner was created. - `creator: Optional[Subject]` creator is the identity of the creator of the environment - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `kind: Optional[RunnerKind]` The runner's kind - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner's name which is shown to users - `provider: Optional[RunnerProvider]` The runner's provider - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `runner_id: Optional[str]` - `runner_manager_id: Optional[str]` The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners. - `spec: Optional[RunnerSpec]` The runner's specification - `configuration: Optional[RunnerConfiguration]` The runner's configuration - `auto_update: Optional[bool]` auto_update indicates whether the runner should automatically update itself. - `devcontainer_image_cache_enabled: Optional[bool]` devcontainer_image_cache_enabled controls whether the devcontainer build cache is enabled for this runner. Only takes effect on supported runners, currently only AWS EC2 and Gitpod-managed runners. - `log_level: Optional[LogLevel]` log_level is the log level for the runner - `"LOG_LEVEL_UNSPECIFIED"` - `"LOG_LEVEL_DEBUG"` - `"LOG_LEVEL_INFO"` - `"LOG_LEVEL_WARN"` - `"LOG_LEVEL_ERROR"` - `metrics: Optional[MetricsConfiguration]` metrics contains configuration for the runner's metrics collection - `enabled: Optional[bool]` enabled indicates whether the runner should collect metrics - `managed_metrics_enabled: Optional[bool]` When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint. - `password: Optional[str]` password is the password to use for the metrics collector - `url: Optional[str]` url is the URL of the metrics collector - `username: Optional[str]` username is the username to use for the metrics collector - `region: Optional[str]` Region to deploy the runner in, if applicable. This is mainly used for remote runners, and is only a hint. The runner may be deployed in a different region. See the runner's status for the actual region. - `release_channel: Optional[RunnerReleaseChannel]` The release channel the runner is on - `"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"` - `"RUNNER_RELEASE_CHANNEL_STABLE"` - `"RUNNER_RELEASE_CHANNEL_LATEST"` - `update_window: Optional[UpdateWindow]` update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time. - `end_hour: Optional[int]` end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2. - `start_hour: Optional[int]` start_hour is the beginning of the update window as a UTC hour (0-23). +required - `desired_phase: Optional[RunnerPhase]` RunnerPhase represents the phase a runner is in - `"RUNNER_PHASE_UNSPECIFIED"` - `"RUNNER_PHASE_CREATED"` - `"RUNNER_PHASE_INACTIVE"` - `"RUNNER_PHASE_ACTIVE"` - `"RUNNER_PHASE_DELETING"` - `"RUNNER_PHASE_DELETED"` - `"RUNNER_PHASE_DEGRADED"` - `variant: Optional[RunnerVariant]` The runner's variant - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` - `status: Optional[RunnerStatus]` The runner's status - `additional_info: Optional[List[FieldValue]]` additional_info contains additional information about the runner, e.g. a CloudFormation stack URL. - `key: Optional[str]` - `value: Optional[str]` - `capabilities: Optional[List[RunnerCapability]]` capabilities is a list of capabilities the runner supports. - `"RUNNER_CAPABILITY_UNSPECIFIED"` - `"RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"` - `"RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"` - `"RUNNER_CAPABILITY_AGENT_EXECUTION"` - `"RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"` - `"RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"` - `"RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"` - `"RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"` - `"RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"` - `"RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"` - `"RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"` - `"RUNNER_CAPABILITY_WARM_POOL"` - `"RUNNER_CAPABILITY_ASG_WARM_POOL"` - `"RUNNER_CAPABILITY_PORT_AUTHENTICATION"` - `gateway_info: Optional[GatewayInfo]` gateway_info is information about the gateway to which the runner is connected. - `gateway: Optional[Gateway]` Gateway represents a system gateway that provides access to services - `name: str` name is the human-readable name of the gateway. name is unique across all gateways. - `url: str` url of the gateway - `region: Optional[str]` region is the geographical region where the gateway is located - `latency: Optional[str]` latency is the round-trip time of the runner to the gateway in milliseconds. - `llm_url: Optional[str]` llm_url is the URL of the LLM service to which the runner is connected. - `log_url: Optional[str]` - `message: Optional[str]` The runner's reported message which is shown to users. This message adds more context to the runner's phase. - `phase: Optional[RunnerPhase]` The runner's reported phase - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `region: Optional[str]` region is the region the runner is running in, if applicable. - `support_bundle_url: Optional[str]` support_bundle_url is the URL at which the runner support bundle can be accessed. This URL provides access to pprof profiles and other debug information. Only available for standalone runners. - `system_details: Optional[str]` - `updated_at: Optional[datetime]` Time when the status was last updated. - `version: Optional[str]` - `updated_at: Optional[datetime]` Time when the Runner was last udpated. ### Runner Search Repositories Response - `class RunnerSearchRepositoriesResponse: …` - `last_page: Optional[int]` Deprecated: Use pagination token instead. Total pages can be extracted from token. - `pagination: Optional[Pagination]` Pagination information for the response. Token format: "NEXT_PAGE/TOTAL_PAGES/TOTAL_COUNT" (e.g., "2/40/1000"). Use -1 for unknown values (e.g., "2/-1/-1" when totals unavailable). Empty token means no more pages. - `next_token: Optional[str]` Token passed for retrieving the next set of results. Empty if there are no more results - `repositories: Optional[List[Repository]]` List of repositories matching the search criteria - `name: Optional[str]` Repository name (e.g., "my-project") - `url: Optional[str]` Repository URL (e.g., "https://github.com/owner/my-project") # Configurations ## ValidateRunnerConfiguration `runners.configurations.validate(ConfigurationValidateParams**kwargs) -> ConfigurationValidateResponse` **post** `/gitpod.v1.RunnerConfigurationService/ValidateRunnerConfiguration` Validates a runner configuration. Use this method to: - Check configuration validity - Verify integration settings - Validate environment classes ### Examples - Validate SCM integration: Checks if an SCM integration is valid. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" scmIntegration: id: "integration-id" scmId: "github" host: "github.com" oauthClientId: "client_id" oauthPlaintextClientSecret: "client_secret" ``` ### Parameters - `environment_class: Optional[EnvironmentClass]` - `id: str` id is the unique identifier of the environment class - `runner_id: str` runner_id is the unique identifier of the runner the environment class belongs to - `configuration: Optional[List[FieldValue]]` configuration describes the configuration of the environment class - `key: Optional[str]` - `value: Optional[str]` - `description: Optional[str]` description is a human readable description of the environment class - `display_name: Optional[str]` display_name is the human readable name of the environment class - `enabled: Optional[bool]` enabled indicates whether the environment class can be used to create new environments. - `runner_id: Optional[str]` - `scm_integration: Optional[ScmIntegration]` - `id: Optional[str]` id is the unique identifier of the SCM integration - `host: Optional[str]` - `issuer_url: Optional[str]` issuer_url can be set to override the authentication provider URL, if it doesn't match the SCM host. - `oauth_client_id: Optional[str]` oauth_client_id is the OAuth app's client ID, if OAuth is configured. If configured, oauth_client_secret must also be set. - `oauth_encrypted_client_secret: Optional[Union[str, Base64FileInput]]` oauth_encrypted_client_secret is the OAuth app's client secret encrypted with the runner's public key, if OAuth is configured. This can be used to e.g. validate an already encrypted client secret of an existing SCM integration. - `oauth_plaintext_client_secret: Optional[str]` oauth_plaintext_client_secret is the OAuth app's client secret in clear text, if OAuth is configured. This can be set to validate any new client secret before it is encrypted and stored. This value will not be stored and get encrypted with the runner's public key before passing it to the runner. - `pat: Optional[bool]` - `scm_id: Optional[str]` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtual_directory: Optional[str]` virtual_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. ### Returns - `class ConfigurationValidateResponse: …` - `environment_class: Optional[EnvironmentClassValidationResult]` - `configuration_errors: Optional[List[FieldValidationError]]` - `error: Optional[str]` - `key: Optional[str]` - `description_error: Optional[str]` - `display_name_error: Optional[str]` - `valid: Optional[bool]` - `scm_integration: Optional[ScmIntegrationValidationResult]` - `host_error: Optional[str]` - `oauth_error: Optional[str]` - `pat_error: Optional[str]` - `scm_id_error: Optional[str]` - `valid: Optional[bool]` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.runners.configurations.validate( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", scm_integration={ "host": "github.com", "id": "integration-id", "oauth_client_id": "client_id", "oauth_plaintext_client_secret": "client_secret", "scm_id": "github", }, ) print(response.environment_class) ``` #### Response ```json { "environmentClass": { "configurationErrors": [ { "error": "error", "key": "key" } ], "descriptionError": "descriptionError", "displayNameError": "displayNameError", "valid": true }, "scmIntegration": { "hostError": "hostError", "oauthError": "oauthError", "patError": "patError", "scmIdError": "scmIdError", "valid": true } } ``` ## Domain Types ### Environment Class Validation Result - `class EnvironmentClassValidationResult: …` - `configuration_errors: Optional[List[FieldValidationError]]` - `error: Optional[str]` - `key: Optional[str]` - `description_error: Optional[str]` - `display_name_error: Optional[str]` - `valid: Optional[bool]` ### Field Validation Error - `class FieldValidationError: …` - `error: Optional[str]` - `key: Optional[str]` ### Scm Integration Validation Result - `class ScmIntegrationValidationResult: …` - `host_error: Optional[str]` - `oauth_error: Optional[str]` - `pat_error: Optional[str]` - `scm_id_error: Optional[str]` - `valid: Optional[bool]` ### Configuration Validate Response - `class ConfigurationValidateResponse: …` - `environment_class: Optional[EnvironmentClassValidationResult]` - `configuration_errors: Optional[List[FieldValidationError]]` - `error: Optional[str]` - `key: Optional[str]` - `description_error: Optional[str]` - `display_name_error: Optional[str]` - `valid: Optional[bool]` - `scm_integration: Optional[ScmIntegrationValidationResult]` - `host_error: Optional[str]` - `oauth_error: Optional[str]` - `pat_error: Optional[str]` - `scm_id_error: Optional[str]` - `valid: Optional[bool]` # Environment Classes ## CreateEnvironmentClass `runners.configurations.environment_classes.create(EnvironmentClassCreateParams**kwargs) -> EnvironmentClassCreateResponse` **post** `/gitpod.v1.RunnerConfigurationService/CreateEnvironmentClass` Creates a new environment class for a runner. Use this method to: - Define compute resources - Configure environment settings - Set up runtime options ### Examples - Create environment class: Creates a new environment configuration. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" displayName: "Large Instance" description: "8 CPU, 16GB RAM" configuration: - key: "cpu" value: "8" - key: "memory" value: "16384" ``` ### Parameters - `configuration: Optional[Iterable[FieldValue]]` - `key: Optional[str]` - `value: Optional[str]` - `description: Optional[str]` - `display_name: Optional[str]` - `runner_id: Optional[str]` ### Returns - `class EnvironmentClassCreateResponse: …` - `id: Optional[str]` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) environment_class = client.runners.configurations.environment_classes.create( configuration=[{ "key": "cpu", "value": "8", }, { "key": "memory", "value": "16384", }], description="8 CPU, 16GB RAM", display_name="Large Instance", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(environment_class.id) ``` #### Response ```json { "id": "id" } ``` ## ListEnvironmentClasses `runners.configurations.environment_classes.list(EnvironmentClassListParams**kwargs) -> SyncEnvironmentClassesPage[EnvironmentClass]` **post** `/gitpod.v1.RunnerConfigurationService/ListEnvironmentClasses` Lists environment classes with optional filtering. Use this method to: - View available classes - Filter by capability - Check enabled status ### Examples - List all classes: Shows all environment classes. ```yaml pagination: pageSize: 20 ``` - Filter enabled classes: Lists only enabled environment classes. ```yaml filter: enabled: true pagination: pageSize: 20 ``` buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `can_create_environments: Optional[bool]` can_create_environments filters the response to only environment classes that can be used to create new environments by the caller. Unlike enabled, which indicates general availability, this ensures the caller only sees environment classes they are allowed to use. - `enabled: Optional[bool]` enabled filters the response to only enabled or disabled environment classes. If not set, all environment classes are returned. - `runner_ids: Optional[Sequence[str]]` runner_ids filters the response to only EnvironmentClasses of these Runner IDs - `runner_kinds: Optional[List[RunnerKind]]` runner_kind filters the response to only environment classes from runners of these kinds. - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `runner_providers: Optional[List[RunnerProvider]]` runner_providers filters the response to only environment classes from runners of these providers. - `"RUNNER_PROVIDER_UNSPECIFIED"` - `"RUNNER_PROVIDER_AWS_EC2"` - `"RUNNER_PROVIDER_LINUX_HOST"` - `"RUNNER_PROVIDER_DESKTOP_MAC"` - `"RUNNER_PROVIDER_MANAGED"` - `"RUNNER_PROVIDER_GCP"` - `"RUNNER_PROVIDER_DEV_AGENT"` - `pagination: Optional[Pagination]` pagination contains the pagination options for listing environment classes - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class EnvironmentClass: …` - `id: str` id is the unique identifier of the environment class - `runner_id: str` runner_id is the unique identifier of the runner the environment class belongs to - `configuration: Optional[List[FieldValue]]` configuration describes the configuration of the environment class - `key: Optional[str]` - `value: Optional[str]` - `description: Optional[str]` description is a human readable description of the environment class - `display_name: Optional[str]` display_name is the human readable name of the environment class - `enabled: Optional[bool]` enabled indicates whether the environment class can be used to create new environments. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.runners.configurations.environment_classes.list( filter={ "enabled": True }, pagination={ "page_size": 20 }, ) page = page.environment_classes[0] print(page.id) ``` #### Response ```json { "environmentClasses": [ { "id": "id", "runnerId": "runnerId", "configuration": [ { "key": "key", "value": "value" } ], "description": "xxx", "displayName": "xxx", "enabled": true } ], "pagination": { "nextToken": "nextToken" } } ``` ## GetEnvironmentClass `runners.configurations.environment_classes.retrieve(EnvironmentClassRetrieveParams**kwargs) -> EnvironmentClassRetrieveResponse` **post** `/gitpod.v1.RunnerConfigurationService/GetEnvironmentClass` Gets details about a specific environment class. Use this method to: - View class configuration - Check resource settings - Verify availability ### Examples - Get class details: Retrieves information about a specific class. ```yaml environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `environment_class_id: Optional[str]` ### Returns - `class EnvironmentClassRetrieveResponse: …` - `environment_class: Optional[EnvironmentClass]` - `id: str` id is the unique identifier of the environment class - `runner_id: str` runner_id is the unique identifier of the runner the environment class belongs to - `configuration: Optional[List[FieldValue]]` configuration describes the configuration of the environment class - `key: Optional[str]` - `value: Optional[str]` - `description: Optional[str]` description is a human readable description of the environment class - `display_name: Optional[str]` display_name is the human readable name of the environment class - `enabled: Optional[bool]` enabled indicates whether the environment class can be used to create new environments. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) environment_class = client.runners.configurations.environment_classes.retrieve( environment_class_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(environment_class.environment_class) ``` #### Response ```json { "environmentClass": { "id": "id", "runnerId": "runnerId", "configuration": [ { "key": "key", "value": "value" } ], "description": "xxx", "displayName": "xxx", "enabled": true } } ``` ## UpdateEnvironmentClass `runners.configurations.environment_classes.update(EnvironmentClassUpdateParams**kwargs) -> object` **post** `/gitpod.v1.RunnerConfigurationService/UpdateEnvironmentClass` Updates an environment class. Use this method to: - Modify class settings - Update resource limits - Change availability ### Examples - Update class: Changes class configuration. ```yaml environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" displayName: "Updated Large Instance" description: "16 CPU, 32GB RAM" enabled: true ``` ### Parameters - `description: Optional[str]` - `display_name: Optional[str]` - `enabled: Optional[bool]` - `environment_class_id: Optional[str]` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) environment_class = client.runners.configurations.environment_classes.update( description="16 CPU, 32GB RAM", display_name="Updated Large Instance", enabled=True, environment_class_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(environment_class) ``` #### Response ```json {} ``` ## Domain Types ### Environment Class Create Response - `class EnvironmentClassCreateResponse: …` - `id: Optional[str]` ### Environment Class Retrieve Response - `class EnvironmentClassRetrieveResponse: …` - `environment_class: Optional[EnvironmentClass]` - `id: str` id is the unique identifier of the environment class - `runner_id: str` runner_id is the unique identifier of the runner the environment class belongs to - `configuration: Optional[List[FieldValue]]` configuration describes the configuration of the environment class - `key: Optional[str]` - `value: Optional[str]` - `description: Optional[str]` description is a human readable description of the environment class - `display_name: Optional[str]` display_name is the human readable name of the environment class - `enabled: Optional[bool]` enabled indicates whether the environment class can be used to create new environments. # Host Authentication Tokens ## CreateHostAuthenticationToken `runners.configurations.host_authentication_tokens.create(HostAuthenticationTokenCreateParams**kwargs) -> HostAuthenticationTokenCreateResponse` **post** `/gitpod.v1.RunnerConfigurationService/CreateHostAuthenticationToken` Creates a new authentication token for accessing remote hosts. Use this method to: - Set up SCM authentication - Configure OAuth credentials - Manage PAT tokens ### Examples - Create OAuth token: Creates a new OAuth-based authentication token. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" userId: "f53d2330-3795-4c5d-a1f3-453121af9c60" host: "github.com" token: "gho_xxxxxxxxxxxx" source: HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH expiresAt: "2024-12-31T23:59:59Z" refreshToken: "ghr_xxxxxxxxxxxx" ``` ### Parameters - `token: Optional[str]` stored encrypted, retrieved via GetHostAuthenticationTokenValue - `expires_at: Optional[Union[str, datetime]]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: Optional[str]` - `integration_id: Optional[str]` - `refresh_token: Optional[str]` stored encrypted, retrieved via GetHostAuthenticationTokenValue - `runner_id: Optional[str]` - `scopes: Optional[Sequence[str]]` Maximum 100 scopes allowed (101 for validation purposes) - `source: Optional[HostAuthenticationTokenSource]` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: Optional[Subject]` Subject identifies the principal (user or service account) for the token - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `user_id: Optional[str]` Deprecated: Use principal_id and principal_type instead ### Returns - `class HostAuthenticationTokenCreateResponse: …` - `token: HostAuthenticationToken` - `id: str` - `expires_at: Optional[datetime]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: Optional[str]` - `integration_id: Optional[str]` links to integration instance - `runner_id: Optional[str]` - `scopes: Optional[List[str]]` token permissions - `source: Optional[HostAuthenticationTokenSource]` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: Optional[Subject]` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `user_id: Optional[str]` Deprecated: Use principal_id and principal_type instead principal (user) ### Example ```python import os from datetime import datetime from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) host_authentication_token = client.runners.configurations.host_authentication_tokens.create( token="gho_xxxxxxxxxxxx", expires_at=datetime.fromisoformat("2024-12-31T23:59:59"), host="github.com", refresh_token="ghr_xxxxxxxxxxxx", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", source="HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH", user_id="f53d2330-3795-4c5d-a1f3-453121af9c60", ) print(host_authentication_token.token) ``` #### Response ```json { "token": { "id": "id", "expiresAt": "2019-12-27T18:11:19.117Z", "host": "host", "integrationId": "integrationId", "runnerId": "runnerId", "scopes": [ "string" ], "source": "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED", "subject": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "userId": "userId" } } ``` ## DeleteHostAuthenticationToken `runners.configurations.host_authentication_tokens.delete(HostAuthenticationTokenDeleteParams**kwargs) -> object` **post** `/gitpod.v1.RunnerConfigurationService/DeleteHostAuthenticationToken` Deletes a host authentication token. Use this method to: - Remove unused tokens - Revoke access - Clean up expired tokens ### Examples - Delete token: Permanently removes a token. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) host_authentication_token = client.runners.configurations.host_authentication_tokens.delete( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(host_authentication_token) ``` #### Response ```json {} ``` ## ListHostAuthenticationTokens `runners.configurations.host_authentication_tokens.list(HostAuthenticationTokenListParams**kwargs) -> SyncTokensPage[HostAuthenticationToken]` **post** `/gitpod.v1.RunnerConfigurationService/ListHostAuthenticationTokens` Lists host authentication tokens with optional filtering. Use this method to: - View all tokens - Filter by runner or user - Monitor token status ### Examples - List all tokens: Shows all tokens with pagination. ```yaml pagination: pageSize: 20 ``` - Filter by runner: Lists tokens for a specific runner. ```yaml filter: runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `runner_id: Optional[str]` - `subject_id: Optional[str]` Filter by subject (user or service account) - `user_id: Optional[str]` Deprecated: Use principal_id instead - `pagination: Optional[Pagination]` - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class HostAuthenticationToken: …` - `id: str` - `expires_at: Optional[datetime]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: Optional[str]` - `integration_id: Optional[str]` links to integration instance - `runner_id: Optional[str]` - `scopes: Optional[List[str]]` token permissions - `source: Optional[HostAuthenticationTokenSource]` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: Optional[Subject]` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `user_id: Optional[str]` Deprecated: Use principal_id and principal_type instead principal (user) ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.runners.configurations.host_authentication_tokens.list( filter={ "runner_id": "d2c94c27-3b76-4a42-b88c-95a85e392c68" }, pagination={ "page_size": 20 }, ) page = page.tokens[0] print(page.id) ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "tokens": [ { "id": "id", "expiresAt": "2019-12-27T18:11:19.117Z", "host": "host", "integrationId": "integrationId", "runnerId": "runnerId", "scopes": [ "string" ], "source": "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED", "subject": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "userId": "userId" } ] } ``` ## GetHostAuthenticationToken `runners.configurations.host_authentication_tokens.retrieve(HostAuthenticationTokenRetrieveParams**kwargs) -> HostAuthenticationTokenRetrieveResponse` **post** `/gitpod.v1.RunnerConfigurationService/GetHostAuthenticationToken` Gets details about a specific host authentication token. Use this method to: - View token information - Check token expiration - Verify token validity ### Examples - Get token details: Retrieves information about a specific token. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `class HostAuthenticationTokenRetrieveResponse: …` - `token: HostAuthenticationToken` - `id: str` - `expires_at: Optional[datetime]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: Optional[str]` - `integration_id: Optional[str]` links to integration instance - `runner_id: Optional[str]` - `scopes: Optional[List[str]]` token permissions - `source: Optional[HostAuthenticationTokenSource]` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: Optional[Subject]` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `user_id: Optional[str]` Deprecated: Use principal_id and principal_type instead principal (user) ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) host_authentication_token = client.runners.configurations.host_authentication_tokens.retrieve( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(host_authentication_token.token) ``` #### Response ```json { "token": { "id": "id", "expiresAt": "2019-12-27T18:11:19.117Z", "host": "host", "integrationId": "integrationId", "runnerId": "runnerId", "scopes": [ "string" ], "source": "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED", "subject": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "userId": "userId" } } ``` ## UpdateHostAuthenticationToken `runners.configurations.host_authentication_tokens.update(HostAuthenticationTokenUpdateParams**kwargs) -> object` **post** `/gitpod.v1.RunnerConfigurationService/UpdateHostAuthenticationToken` Updates an existing host authentication token. Use this method to: - Refresh token values - Update expiration - Modify token settings ### Examples - Update token: Updates token value and expiration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" token: "gho_xxxxxxxxxxxx" expiresAt: "2024-12-31T23:59:59Z" refreshToken: "ghr_xxxxxxxxxxxx" ``` ### Parameters - `id: Optional[str]` - `token: Optional[str]` - `expires_at: Optional[Union[str, datetime, null]]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `refresh_token: Optional[str]` - `scopes: Optional[Sequence[str]]` ### Returns - `object` ### Example ```python import os from datetime import datetime from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) host_authentication_token = client.runners.configurations.host_authentication_tokens.update( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", token="gho_xxxxxxxxxxxx", expires_at=datetime.fromisoformat("2024-12-31T23:59:59"), refresh_token="ghr_xxxxxxxxxxxx", ) print(host_authentication_token) ``` #### Response ```json {} ``` ## Domain Types ### Host Authentication Token - `class HostAuthenticationToken: …` - `id: str` - `expires_at: Optional[datetime]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: Optional[str]` - `integration_id: Optional[str]` links to integration instance - `runner_id: Optional[str]` - `scopes: Optional[List[str]]` token permissions - `source: Optional[HostAuthenticationTokenSource]` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: Optional[Subject]` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `user_id: Optional[str]` Deprecated: Use principal_id and principal_type instead principal (user) ### Host Authentication Token Source - `Literal["HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED", "HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH", "HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"]` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` ### Host Authentication Token Create Response - `class HostAuthenticationTokenCreateResponse: …` - `token: HostAuthenticationToken` - `id: str` - `expires_at: Optional[datetime]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: Optional[str]` - `integration_id: Optional[str]` links to integration instance - `runner_id: Optional[str]` - `scopes: Optional[List[str]]` token permissions - `source: Optional[HostAuthenticationTokenSource]` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: Optional[Subject]` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `user_id: Optional[str]` Deprecated: Use principal_id and principal_type instead principal (user) ### Host Authentication Token Retrieve Response - `class HostAuthenticationTokenRetrieveResponse: …` - `token: HostAuthenticationToken` - `id: str` - `expires_at: Optional[datetime]` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: Optional[str]` - `integration_id: Optional[str]` links to integration instance - `runner_id: Optional[str]` - `scopes: Optional[List[str]]` token permissions - `source: Optional[HostAuthenticationTokenSource]` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: Optional[Subject]` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `user_id: Optional[str]` Deprecated: Use principal_id and principal_type instead principal (user) # Schema ## GetRunnerConfigurationSchema `runners.configurations.schema.retrieve(SchemaRetrieveParams**kwargs) -> SchemaRetrieveResponse` **post** `/gitpod.v1.RunnerConfigurationService/GetRunnerConfigurationSchema` Gets the latest runner configuration schema. Use this method to: - View available settings - Check configuration options - Validate configurations ### Examples - Get schema: Retrieves configuration schema for a runner. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `runner_id: Optional[str]` ### Returns - `class SchemaRetrieveResponse: …` - `schema: Optional[RunnerConfigurationSchema]` - `environment_classes: Optional[List[EnvironmentClass]]` - `id: Optional[str]` - `bool: Optional[EnvironmentClassBool]` - `default: Optional[bool]` - `description: Optional[str]` - `display: Optional[EnvironmentClassDisplay]` - `default: Optional[str]` - `enum: Optional[EnvironmentClassEnum]` - `default: Optional[str]` deprecated, will be removed, use default_value instead - `default_value: Optional[EnvironmentClassEnumDefaultValue]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `possible_values: Optional[List[EnvironmentClassEnumPossibleValue]]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `values: Optional[List[str]]` deprecated, will be removed, use possible_values instead - `int: Optional[EnvironmentClassInt]` - `default: Optional[int]` - `max: Optional[int]` - `min: Optional[int]` - `name: Optional[str]` - `required: Optional[bool]` - `secret: Optional[bool]` - `string: Optional[EnvironmentClassString]` - `default: Optional[str]` - `pattern: Optional[str]` - `runner_config: Optional[List[RunnerConfig]]` - `id: Optional[str]` - `bool: Optional[RunnerConfigBool]` - `default: Optional[bool]` - `description: Optional[str]` - `display: Optional[RunnerConfigDisplay]` - `default: Optional[str]` - `enum: Optional[RunnerConfigEnum]` - `default: Optional[str]` deprecated, will be removed, use default_value instead - `default_value: Optional[RunnerConfigEnumDefaultValue]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `possible_values: Optional[List[RunnerConfigEnumPossibleValue]]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `values: Optional[List[str]]` deprecated, will be removed, use possible_values instead - `int: Optional[RunnerConfigInt]` - `default: Optional[int]` - `max: Optional[int]` - `min: Optional[int]` - `name: Optional[str]` - `required: Optional[bool]` - `secret: Optional[bool]` - `string: Optional[RunnerConfigString]` - `default: Optional[str]` - `pattern: Optional[str]` - `scm: Optional[List[Scm]]` - `default_hosts: Optional[List[str]]` - `name: Optional[str]` - `oauth: Optional[ScmOAuth]` - `callback_url: Optional[str]` callback_url is the URL the OAuth app will redirect to after the user has authenticated. - `pat: Optional[ScmPat]` - `description: Optional[str]` description is a human-readable description of the PAT. - `docs_link: Optional[str]` docs_link is a link to the documentation on how to create a PAT for this SCM system. - `scm_id: Optional[str]` - `version: Optional[str]` The schema version ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) schema = client.runners.configurations.schema.retrieve( runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(schema.schema) ``` #### Response ```json { "schema": { "environmentClasses": [ { "id": "id", "bool": { "default": true }, "description": "description", "display": { "default": "default" }, "enum": { "default": "default", "defaultValue": { "detail": "detail", "subtitle": "subtitle", "title": "title" }, "possibleValues": [ { "detail": "detail", "subtitle": "subtitle", "title": "title" } ], "values": [ "string" ] }, "int": { "default": 0, "max": 0, "min": 0 }, "name": "name", "required": true, "secret": true, "string": { "default": "default", "pattern": "pattern" } } ], "runnerConfig": [ { "id": "id", "bool": { "default": true }, "description": "description", "display": { "default": "default" }, "enum": { "default": "default", "defaultValue": { "detail": "detail", "subtitle": "subtitle", "title": "title" }, "possibleValues": [ { "detail": "detail", "subtitle": "subtitle", "title": "title" } ], "values": [ "string" ] }, "int": { "default": 0, "max": 0, "min": 0 }, "name": "name", "required": true, "secret": true, "string": { "default": "default", "pattern": "pattern" } } ], "scm": [ { "defaultHosts": [ "string" ], "name": "name", "oauth": { "callbackUrl": "callbackUrl" }, "pat": { "description": "description", "docsLink": "docsLink" }, "scmId": "scmId" } ], "version": "version" } } ``` ## Domain Types ### Runner Configuration Schema - `class RunnerConfigurationSchema: …` - `environment_classes: Optional[List[EnvironmentClass]]` - `id: Optional[str]` - `bool: Optional[EnvironmentClassBool]` - `default: Optional[bool]` - `description: Optional[str]` - `display: Optional[EnvironmentClassDisplay]` - `default: Optional[str]` - `enum: Optional[EnvironmentClassEnum]` - `default: Optional[str]` deprecated, will be removed, use default_value instead - `default_value: Optional[EnvironmentClassEnumDefaultValue]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `possible_values: Optional[List[EnvironmentClassEnumPossibleValue]]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `values: Optional[List[str]]` deprecated, will be removed, use possible_values instead - `int: Optional[EnvironmentClassInt]` - `default: Optional[int]` - `max: Optional[int]` - `min: Optional[int]` - `name: Optional[str]` - `required: Optional[bool]` - `secret: Optional[bool]` - `string: Optional[EnvironmentClassString]` - `default: Optional[str]` - `pattern: Optional[str]` - `runner_config: Optional[List[RunnerConfig]]` - `id: Optional[str]` - `bool: Optional[RunnerConfigBool]` - `default: Optional[bool]` - `description: Optional[str]` - `display: Optional[RunnerConfigDisplay]` - `default: Optional[str]` - `enum: Optional[RunnerConfigEnum]` - `default: Optional[str]` deprecated, will be removed, use default_value instead - `default_value: Optional[RunnerConfigEnumDefaultValue]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `possible_values: Optional[List[RunnerConfigEnumPossibleValue]]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `values: Optional[List[str]]` deprecated, will be removed, use possible_values instead - `int: Optional[RunnerConfigInt]` - `default: Optional[int]` - `max: Optional[int]` - `min: Optional[int]` - `name: Optional[str]` - `required: Optional[bool]` - `secret: Optional[bool]` - `string: Optional[RunnerConfigString]` - `default: Optional[str]` - `pattern: Optional[str]` - `scm: Optional[List[Scm]]` - `default_hosts: Optional[List[str]]` - `name: Optional[str]` - `oauth: Optional[ScmOAuth]` - `callback_url: Optional[str]` callback_url is the URL the OAuth app will redirect to after the user has authenticated. - `pat: Optional[ScmPat]` - `description: Optional[str]` description is a human-readable description of the PAT. - `docs_link: Optional[str]` docs_link is a link to the documentation on how to create a PAT for this SCM system. - `scm_id: Optional[str]` - `version: Optional[str]` The schema version ### Schema Retrieve Response - `class SchemaRetrieveResponse: …` - `schema: Optional[RunnerConfigurationSchema]` - `environment_classes: Optional[List[EnvironmentClass]]` - `id: Optional[str]` - `bool: Optional[EnvironmentClassBool]` - `default: Optional[bool]` - `description: Optional[str]` - `display: Optional[EnvironmentClassDisplay]` - `default: Optional[str]` - `enum: Optional[EnvironmentClassEnum]` - `default: Optional[str]` deprecated, will be removed, use default_value instead - `default_value: Optional[EnvironmentClassEnumDefaultValue]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `possible_values: Optional[List[EnvironmentClassEnumPossibleValue]]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `values: Optional[List[str]]` deprecated, will be removed, use possible_values instead - `int: Optional[EnvironmentClassInt]` - `default: Optional[int]` - `max: Optional[int]` - `min: Optional[int]` - `name: Optional[str]` - `required: Optional[bool]` - `secret: Optional[bool]` - `string: Optional[EnvironmentClassString]` - `default: Optional[str]` - `pattern: Optional[str]` - `runner_config: Optional[List[RunnerConfig]]` - `id: Optional[str]` - `bool: Optional[RunnerConfigBool]` - `default: Optional[bool]` - `description: Optional[str]` - `display: Optional[RunnerConfigDisplay]` - `default: Optional[str]` - `enum: Optional[RunnerConfigEnum]` - `default: Optional[str]` deprecated, will be removed, use default_value instead - `default_value: Optional[RunnerConfigEnumDefaultValue]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `possible_values: Optional[List[RunnerConfigEnumPossibleValue]]` - `detail: Optional[str]` - `subtitle: Optional[str]` - `title: Optional[str]` - `values: Optional[List[str]]` deprecated, will be removed, use possible_values instead - `int: Optional[RunnerConfigInt]` - `default: Optional[int]` - `max: Optional[int]` - `min: Optional[int]` - `name: Optional[str]` - `required: Optional[bool]` - `secret: Optional[bool]` - `string: Optional[RunnerConfigString]` - `default: Optional[str]` - `pattern: Optional[str]` - `scm: Optional[List[Scm]]` - `default_hosts: Optional[List[str]]` - `name: Optional[str]` - `oauth: Optional[ScmOAuth]` - `callback_url: Optional[str]` callback_url is the URL the OAuth app will redirect to after the user has authenticated. - `pat: Optional[ScmPat]` - `description: Optional[str]` description is a human-readable description of the PAT. - `docs_link: Optional[str]` docs_link is a link to the documentation on how to create a PAT for this SCM system. - `scm_id: Optional[str]` - `version: Optional[str]` The schema version # Scm Integrations ## CreateSCMIntegration `runners.configurations.scm_integrations.create(ScmIntegrationCreateParams**kwargs) -> ScmIntegrationCreateResponse` **post** `/gitpod.v1.RunnerConfigurationService/CreateSCMIntegration` Creates a new SCM integration for a runner. Use this method to: - Configure source control access - Set up repository integrations - Enable code synchronization ### Examples - Create GitHub integration: Sets up GitHub SCM integration. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" scmId: "github" host: "github.com" oauthClientId: "client_id" oauthPlaintextClientSecret: "client_secret" ``` ### Parameters - `host: Optional[str]` - `issuer_url: Optional[str]` issuer_url can be set to override the authentication provider URL, if it doesn't match the SCM host. - `oauth_client_id: Optional[str]` oauth_client_id is the OAuth app's client ID, if OAuth is configured. If configured, oauth_plaintext_client_secret must also be set. - `oauth_plaintext_client_secret: Optional[str]` oauth_plaintext_client_secret is the OAuth app's client secret in clear text. This will first be encrypted with the runner's public key before being stored. - `pat: Optional[bool]` - `runner_id: Optional[str]` - `scm_id: Optional[str]` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtual_directory: Optional[str]` virtual_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. ### Returns - `class ScmIntegrationCreateResponse: …` - `id: Optional[str]` id is a uniquely generated identifier for the SCM integration ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) scm_integration = client.runners.configurations.scm_integrations.create( host="github.com", oauth_client_id="client_id", oauth_plaintext_client_secret="client_secret", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", scm_id="github", ) print(scm_integration.id) ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } ``` ## DeleteSCMIntegration `runners.configurations.scm_integrations.delete(ScmIntegrationDeleteParams**kwargs) -> object` **post** `/gitpod.v1.RunnerConfigurationService/DeleteSCMIntegration` Deletes an SCM integration. Use this method to: - Remove unused integrations - Clean up configurations - Revoke SCM access ### Examples - Delete integration: Removes an SCM integration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) scm_integration = client.runners.configurations.scm_integrations.delete( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(scm_integration) ``` #### Response ```json {} ``` ## ListSCMIntegrations `runners.configurations.scm_integrations.list(ScmIntegrationListParams**kwargs) -> SyncIntegrationsPage[ScmIntegration]` **post** `/gitpod.v1.RunnerConfigurationService/ListSCMIntegrations` Lists SCM integrations for a runner. Use this method to: - View all integrations - Monitor integration status - Check available SCMs ### Examples - List integrations: Shows all SCM integrations. ```yaml filter: runnerIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `runner_ids: Optional[Sequence[str]]` runner_ids filters the response to only SCM integrations of these Runner IDs - `pagination: Optional[Pagination]` pagination contains the pagination options for listing scm integrations - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class ScmIntegration: …` - `id: Optional[str]` id is the unique identifier of the SCM integration - `host: Optional[str]` - `oauth: Optional[ScmIntegrationOAuthConfig]` - `client_id: Optional[str]` client_id is the OAuth app's client ID in clear text. - `encrypted_client_secret: Optional[str]` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuer_url: Optional[str]` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: Optional[bool]` - `runner_id: Optional[str]` - `scm_id: Optional[str]` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtual_directory: Optional[str]` virtual_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.runners.configurations.scm_integrations.list( filter={ "runner_ids": ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] }, pagination={ "page_size": 20 }, ) page = page.integrations[0] print(page.id) ``` #### Response ```json { "integrations": [ { "id": "id", "host": "host", "oauth": { "clientId": "clientId", "encryptedClientSecret": "U3RhaW5sZXNzIHJvY2tz", "issuerUrl": "issuerUrl" }, "pat": true, "runnerId": "runnerId", "scmId": "scmId", "virtualDirectory": "virtualDirectory" } ], "pagination": { "nextToken": "nextToken" } } ``` ## GetSCMIntegration `runners.configurations.scm_integrations.retrieve(ScmIntegrationRetrieveParams**kwargs) -> ScmIntegrationRetrieveResponse` **post** `/gitpod.v1.RunnerConfigurationService/GetSCMIntegration` Gets details about a specific SCM integration. Use this method to: - View integration settings - Check integration status - Verify configuration ### Examples - Get integration details: Retrieves information about a specific integration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `class ScmIntegrationRetrieveResponse: …` - `integration: Optional[ScmIntegration]` - `id: Optional[str]` id is the unique identifier of the SCM integration - `host: Optional[str]` - `oauth: Optional[ScmIntegrationOAuthConfig]` - `client_id: Optional[str]` client_id is the OAuth app's client ID in clear text. - `encrypted_client_secret: Optional[str]` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuer_url: Optional[str]` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: Optional[bool]` - `runner_id: Optional[str]` - `scm_id: Optional[str]` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtual_directory: Optional[str]` virtual_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) scm_integration = client.runners.configurations.scm_integrations.retrieve( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(scm_integration.integration) ``` #### Response ```json { "integration": { "id": "id", "host": "host", "oauth": { "clientId": "clientId", "encryptedClientSecret": "U3RhaW5sZXNzIHJvY2tz", "issuerUrl": "issuerUrl" }, "pat": true, "runnerId": "runnerId", "scmId": "scmId", "virtualDirectory": "virtualDirectory" } } ``` ## UpdateSCMIntegration `runners.configurations.scm_integrations.update(ScmIntegrationUpdateParams**kwargs) -> object` **post** `/gitpod.v1.RunnerConfigurationService/UpdateSCMIntegration` Updates an existing SCM integration. Use this method to: - Modify integration settings - Update credentials - Change configuration ### Examples - Update integration: Updates OAuth credentials. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" oauthClientId: "new_client_id" oauthPlaintextClientSecret: "new_client_secret" ``` ### Parameters - `id: Optional[str]` - `issuer_url: Optional[str]` issuer_url can be set to override the authentication provider URL, if it doesn't match the SCM host. - `oauth_client_id: Optional[str]` oauth_client_id can be set to update the OAuth app's client ID. If an empty string is set, the OAuth configuration will be removed (regardless of whether a client secret is set), and any existing Host Authentication Tokens for the SCM integration's runner and host that were created using the OAuth app will be deleted. This might lead to users being unable to access their repositories until they re-authenticate. - `oauth_plaintext_client_secret: Optional[str]` oauth_plaintext_client_secret can be set to update the OAuth app's client secret. The cleartext secret will be encrypted with the runner's public key before being stored. - `pat: Optional[bool]` pat can be set to enable or disable Personal Access Tokens support. When disabling PATs, any existing Host Authentication Tokens for the SCM integration's runner and host that were created using a PAT will be deleted. This might lead to users being unable to access their repositories until they re-authenticate. - `virtual_directory: Optional[str]` virtual_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) scm_integration = client.runners.configurations.scm_integrations.update( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", oauth_client_id="new_client_id", oauth_plaintext_client_secret="new_client_secret", ) print(scm_integration) ``` #### Response ```json {} ``` ## Domain Types ### Scm Integration - `class ScmIntegration: …` - `id: Optional[str]` id is the unique identifier of the SCM integration - `host: Optional[str]` - `oauth: Optional[ScmIntegrationOAuthConfig]` - `client_id: Optional[str]` client_id is the OAuth app's client ID in clear text. - `encrypted_client_secret: Optional[str]` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuer_url: Optional[str]` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: Optional[bool]` - `runner_id: Optional[str]` - `scm_id: Optional[str]` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtual_directory: Optional[str]` virtual_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. ### Scm Integration OAuth Config - `class ScmIntegrationOAuthConfig: …` - `client_id: Optional[str]` client_id is the OAuth app's client ID in clear text. - `encrypted_client_secret: Optional[str]` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuer_url: Optional[str]` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. ### Scm Integration Create Response - `class ScmIntegrationCreateResponse: …` - `id: Optional[str]` id is a uniquely generated identifier for the SCM integration ### Scm Integration Retrieve Response - `class ScmIntegrationRetrieveResponse: …` - `integration: Optional[ScmIntegration]` - `id: Optional[str]` id is the unique identifier of the SCM integration - `host: Optional[str]` - `oauth: Optional[ScmIntegrationOAuthConfig]` - `client_id: Optional[str]` client_id is the OAuth app's client ID in clear text. - `encrypted_client_secret: Optional[str]` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuer_url: Optional[str]` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: Optional[bool]` - `runner_id: Optional[str]` - `scm_id: Optional[str]` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtual_directory: Optional[str]` virtual_directory is the virtual directory path for Azure DevOps Server (e.g., "/tfs"). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is 'All accessible organizations'. # Policies ## CreateRunnerPolicy `runners.policies.create(PolicyCreateParams**kwargs) -> PolicyCreateResponse` **post** `/gitpod.v1.RunnerService/CreateRunnerPolicy` Creates a new policy for a runner. Use this method to: - Set up access controls - Define group permissions - Configure role-based access ### Examples - Create admin policy: Grants admin access to a group. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60" role: RUNNER_ROLE_ADMIN ``` ### Parameters - `group_id: Optional[str]` group_id specifies the group_id identifier - `role: Optional[RunnerRole]` - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` - `runner_id: Optional[str]` runner_id specifies the project identifier ### Returns - `class PolicyCreateResponse: …` - `policy: RunnerPolicy` - `group_id: Optional[str]` - `role: Optional[RunnerRole]` role is the role assigned to the group - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) policy = client.runners.policies.create( group_id="f53d2330-3795-4c5d-a1f3-453121af9c60", role="RUNNER_ROLE_ADMIN", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(policy.policy) ``` #### Response ```json { "policy": { "groupId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "role": "RUNNER_ROLE_UNSPECIFIED" } } ``` ## DeleteRunnerPolicy `runners.policies.delete(PolicyDeleteParams**kwargs) -> object` **post** `/gitpod.v1.RunnerService/DeleteRunnerPolicy` Deletes a runner policy. Use this method to: - Remove access controls - Revoke permissions - Clean up policies ### Examples - Delete policy: Removes a group's access policy. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60" ``` ### Parameters - `group_id: Optional[str]` group_id specifies the group_id identifier - `runner_id: Optional[str]` runner_id specifies the project identifier ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) policy = client.runners.policies.delete( group_id="f53d2330-3795-4c5d-a1f3-453121af9c60", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(policy) ``` #### Response ```json {} ``` ## ListRunnerPolicies `runners.policies.list(PolicyListParams**kwargs) -> SyncPoliciesPage[RunnerPolicy]` **post** `/gitpod.v1.RunnerService/ListRunnerPolicies` Lists policies for a runner. Use this method to: - View access controls - Check policy configurations - Audit permissions ### Examples - List policies: Shows all policies for a runner. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `pagination: Optional[Pagination]` pagination contains the pagination options for listing project policies - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. - `runner_id: Optional[str]` runner_id specifies the project identifier ### Returns - `class RunnerPolicy: …` - `group_id: Optional[str]` - `role: Optional[RunnerRole]` role is the role assigned to the group - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.runners.policies.list( pagination={ "page_size": 20 }, runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) page = page.policies[0] print(page.group_id) ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "policies": [ { "groupId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "role": "RUNNER_ROLE_UNSPECIFIED" } ] } ``` ## UpdateRunnerPolicy `runners.policies.update(PolicyUpdateParams**kwargs) -> PolicyUpdateResponse` **post** `/gitpod.v1.RunnerService/UpdateRunnerPolicy` Updates an existing runner policy. Use this method to: - Modify access levels - Change group roles - Update permissions ### Examples - Update policy role: Changes a group's access level. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60" role: RUNNER_ROLE_USER ``` ### Parameters - `group_id: Optional[str]` group_id specifies the group_id identifier - `role: Optional[RunnerRole]` - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` - `runner_id: Optional[str]` runner_id specifies the project identifier ### Returns - `class PolicyUpdateResponse: …` - `policy: RunnerPolicy` - `group_id: Optional[str]` - `role: Optional[RunnerRole]` role is the role assigned to the group - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) policy = client.runners.policies.update( group_id="f53d2330-3795-4c5d-a1f3-453121af9c60", role="RUNNER_ROLE_USER", runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(policy.policy) ``` #### Response ```json { "policy": { "groupId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "role": "RUNNER_ROLE_UNSPECIFIED" } } ``` ## Domain Types ### Runner Policy - `class RunnerPolicy: …` - `group_id: Optional[str]` - `role: Optional[RunnerRole]` role is the role assigned to the group - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` ### Runner Role - `Literal["RUNNER_ROLE_UNSPECIFIED", "RUNNER_ROLE_ADMIN", "RUNNER_ROLE_USER"]` - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` ### Policy Create Response - `class PolicyCreateResponse: …` - `policy: RunnerPolicy` - `group_id: Optional[str]` - `role: Optional[RunnerRole]` role is the role assigned to the group - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"` ### Policy Update Response - `class PolicyUpdateResponse: …` - `policy: RunnerPolicy` - `group_id: Optional[str]` - `role: Optional[RunnerRole]` role is the role assigned to the group - `"RUNNER_ROLE_UNSPECIFIED"` - `"RUNNER_ROLE_ADMIN"` - `"RUNNER_ROLE_USER"`