Gitpod API Reference | Runners

Runners

runners

Methods

Check Authentication For Host -> { authenticated, authenticationUrl, patSupported, 4 more... }

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.
```
host: "github.com"
```

Create Runner -> { runner, accessToken, exchangeToken }

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.

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.

name: "Local Development Runner"
provider: RUNNER_PROVIDER_LINUX_HOST
spec:
  desiredPhase: RUNNER_PHASE_ACTIVE
  configuration:
    releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
    autoUpdate: true

Response fields

runner:

Runner

accessToken: string

Optional

Deprecated

deprecated, will be removed. Use exchange_token instead.

exchangeToken: string

Optional

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.

Request example

curl https://app.gitpod.io/api/gitpod.v1.RunnerService/CreateRunner \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

200Example

{
  "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,
        "devcontainerImageCacheEnabled": true,
        "logLevel": "LOG_LEVEL_UNSPECIFIED",
        "metrics": {
          "enabled": true,
          "password": "password",
          "url": "url",
          "username": "username"
        },
        "region": "region",
        "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED"
      },
      "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"
}

Create Runner Logs Token -> { accessToken }

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:

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"

Create Runner Token -> { accessToken, exchangeToken }

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.
```
runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Delete Runner -> unknown

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"

List Runners -> RunnersPage<

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.
```
pagination:
  pageSize: 20
```

Filter by provider:

Lists only AWS EC2 runners.

filter:
  providers: ["RUNNER_PROVIDER_AWS_EC2"]
pagination:
  pageSize: 20

Parse Context URL -> { git, issue, originalContextUrl, 4 more... }

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.

contextUrl: "https://github.com/org/repo/tree/main"

Get Runner -> { runner }

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.
```
runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Search Repositories -> { lastPage, pagination, repositories }

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.
```
runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Search repositories:

Searches for repositories matching the query across all hosts.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
searchString: "my-project"
limit: 10

Update Runner -> unknown

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
name: "Updated Runner Name"
spec:
  configuration:
    releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
    autoUpdate: true

Domain types

GatewayInfo = { gateway, latency }

LogLevel = "LOG_LEVEL_UNSPECIFIED" | "LOG_LEVEL_DEBUG" | "LOG_LEVEL_INFO" | 2 more...

MetricsConfiguration = { enabled, password, url, 1 more... }

Runner = { createdAt, creator, kind, 7 more... }

RunnerCapability = "RUNNER_CAPABILITY_UNSPECIFIED" | "RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS" | "RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY" | 4 more...

RunnerConfiguration = { autoUpdate, devcontainerImageCacheEnabled, logLevel, 3 more... }

RunnerKind = "RUNNER_KIND_UNSPECIFIED" | "RUNNER_KIND_LOCAL" | "RUNNER_KIND_REMOTE" | 1 more...

RunnerKind represents the kind of a runner

RunnerPhase = "RUNNER_PHASE_UNSPECIFIED" | "RUNNER_PHASE_CREATED" | "RUNNER_PHASE_INACTIVE" | 4 more...

RunnerPhase represents the phase a runner is in

RunnerProvider = "RUNNER_PROVIDER_UNSPECIFIED" | "RUNNER_PROVIDER_AWS_EC2" | "RUNNER_PROVIDER_LINUX_HOST" | 3 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.

RunnerReleaseChannel = "RUNNER_RELEASE_CHANNEL_UNSPECIFIED" | "RUNNER_RELEASE_CHANNEL_STABLE" | "RUNNER_RELEASE_CHANNEL_LATEST"

RunnerSpec = { configuration, desiredPhase, variant }

RunnerStatus = { additionalInfo, capabilities, gatewayInfo, 10 more... }

RunnerStatus represents the status of a runner

RunnerVariant = "RUNNER_VARIANT_UNSPECIFIED" | "RUNNER_VARIANT_STANDARD" | "RUNNER_VARIANT_ENTERPRISE"

SearchMode = "SEARCH_MODE_UNSPECIFIED" | "SEARCH_MODE_KEYWORD" | "SEARCH_MODE_NATIVE"

Runners

Configurations

runners.configurations

Methods

Validate Runner Configuration -> { environmentClass, scmIntegration }

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
scmIntegration:
  id: "integration-id"
  scmId: "github"
  host: "github.com"
  oauthClientId: "client_id"
  oauthPlaintextClientSecret: "client_secret"

Domain types

EnvironmentClassValidationResult = { configurationErrors, descriptionError, displayNameError, 1 more... }

FieldValidationError = { error, key }

ScmIntegrationValidationResult = { hostError, oauthError, patError, 2 more... }

Runners Configurations

Environment Classes

runners.configurations.environment_classes

Methods

Create Environment Class -> { id }

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
displayName: "Large Instance"
description: "8 CPU, 16GB RAM"
configuration:
  - key: "cpu"
    value: "8"
  - key: "memory"
    value: "16384"

List Environment Classes -> EnvironmentClassesPage<

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.
```
pagination:
  pageSize: 20
```
Filter enabled classes:

Lists only enabled environment classes.
```
filter:
  enabled: true
pagination:
  pageSize: 20
```

buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE

Get Environment Class -> { environmentClass }

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.
```
environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Update Environment Class -> unknown

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.

environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
displayName: "Updated Large Instance"
description: "16 CPU, 32GB RAM"
enabled: true

Runners Configurations

Host Authentication Tokens

runners.configurations.host_authentication_tokens

Methods

Create Host Authentication Token -> { token }

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.

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"

Delete Host Authentication Token -> unknown

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.

id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"

List Host Authentication Tokens -> TokensPage<

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.
```
pagination:
  pageSize: 20
```

Filter by runner:

Lists tokens for a specific runner.

filter:
  runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
pagination:
  pageSize: 20

Get Host Authentication Token -> { token }

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.
```
id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Update Host Authentication Token -> unknown

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.

id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
token: "gho_xxxxxxxxxxxx"
expiresAt: "2024-12-31T23:59:59Z"
refreshToken: "ghr_xxxxxxxxxxxx"

Domain types

HostAuthenticationToken = { id, expiresAt, host, 6 more... }

HostAuthenticationTokenSource = "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED" | "HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH" | "HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"

Runners Configurations

Schema

runners.configurations.schema

Methods

Get Runner Configuration Schema -> { schema }

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.
```
runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Domain types

RunnerConfigurationSchema = { environmentClasses, runnerConfig, scm, 1 more... }

Runners Configurations

Scm Integrations

runners.configurations.scm_integrations

Methods

Create Scm Integration -> { id }

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
scmId: "github"
host: "github.com"
oauthClientId: "client_id"
oauthPlaintextClientSecret: "client_secret"

Delete Scm Integration -> unknown

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.
```
id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

List Scm Integrations -> IntegrationsPage<

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.

filter:
  runnerIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"]
pagination:
  pageSize: 20

Get Scm Integration -> { integration }

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.
```
id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
```

Update Scm Integration -> unknown

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.

id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
oauthClientId: "new_client_id"
oauthPlaintextClientSecret: "new_client_secret"

Domain types

ScmIntegration = { id, host, oauth, 4 more... }

ScmIntegrationOAuthConfig = { clientId, encryptedClientSecret, issuerUrl }

Runners

Policies

runners.policies

Methods

Create Runner Policy -> { policy }

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: RUNNER_ROLE_ADMIN

Delete Runner Policy -> unknown

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"

List Runner Policies -> PoliciesPage<

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
pagination:
  pageSize: 20

Update Runner Policy -> { policy }

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.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: RUNNER_ROLE_USER

Domain types

RunnerPolicy = { groupId, role }

RunnerRole = "RUNNER_ROLE_UNSPECIFIED" | "RUNNER_ROLE_ADMIN" | "RUNNER_ROLE_USER"