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": "id",
      "principal": "PRINCIPAL_UNSPECIFIED"
    },
    "kind": "RUNNER_KIND_UNSPECIFIED",
    "name": "name",
    "provider": "RUNNER_PROVIDER_UNSPECIFIED",
    "runnerId": "runnerId",
    "spec": {
      "configuration": {
        "autoUpdate": true,
        "region": "region",
        "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED"
      },
      "desiredPhase": "RUNNER_PHASE_UNSPECIFIED"
    },
    "status": {
      "additionalInfo": [
        {
          "key": "key",
          "value": "value"
        }
      ],
      "capabilities": [
        "RUNNER_CAPABILITY_UNSPECIFIED"
      ],
      "logUrl": "logUrl",
      "message": "message",
      "phase": "RUNNER_PHASE_UNSPECIFIED",
      "region": "region",
      "systemDetails": "systemDetails",
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "version": "version"
    },
    "updatedAt": "2019-12-27T18:11:19.117Z"
  },
  "accessToken": "accessToken",
  "exchangeToken": "exchangeToken"
}

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, originalContextUrl }

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"
```

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

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

RunnerCapability = "RUNNER_CAPABILITY_UNSPECIFIED" | "RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS" | "RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"

RunnerConfiguration = { autoUpdate, region, releaseChannel }

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" | 1 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 }

RunnerStatus = { additionalInfo, capabilities, logUrl, 6 more... }

RunnerStatus represents the status of a runner

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, 3 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, 3 more... }

ScmIntegrationOAuthConfig = { clientId, encryptedClientSecret }

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"