Gitpod Documentation | Runners

Runners

runners

Methods

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

post/gitpod.v1.RunnerService/CheckAuthenticationForHost

CheckAuthenticationForHost asks a runner if the user is authenticated against a particular host, e.g. an SCM system. If not, this function will return a URL that the user should visit to authenticate, or indicate that Personal Access Tokens are supported.

Create Runner -> { accessToken, runner }

post/gitpod.v1.RunnerService/CreateRunner

CreateRunner creates a new runner with the server. Registrations are very short-lived and must be renewed every 30 seconds. Runners can be registered for an entire organisation or a single user.

Create Runner Token -> { accessToken }

post/gitpod.v1.RunnerService/CreateRunnerToken

CreateRunnerToken returns a token that can be used to authenticate as the runner. Use this call to renew an outdated token - this does not expire any previouly issued tokens.

Delete Runner -> unknown

post/gitpod.v1.RunnerService/DeleteRunner

DeleteRunner deletes an environment runner.

List Runners -> RunnersPage<{ createdAt, creator, kind, 6 more... }>

post/gitpod.v1.RunnerService/ListRunners

ListRunners returns all runners registered in the scope.

Parse Context URL -> { git, originalContextUrl }

post/gitpod.v1.RunnerService/ParseContextURL

ParseContextURL asks a runner to parse a context URL, and return the parsed result.

This call returns

FAILED_PRECONDITION if the user requires authentication on the runner to access the context URL
PERMISSION_DENIED if the user is not allowed to access the context URL using the credentials they have
INVALID_ARGUMENT if the context URL is invalid
NOT_FOUND if the repository or branch indicated by the context URL does not exist

Get Runner -> { runner }

post/gitpod.v1.RunnerService/GetRunner

GetRunner returns a single runner.

Security

Bearer Auth

Example: Authorization: Bearer My Bearer Token

Response fields

runner: { createdAt, creator, kind, 6 more... }

Optional

Request example

curl https://app.gitpod.io/api/gitpod.v1.RunnerService/GetRunner \
    -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"
  }
}

Update Runner -> unknown

post/gitpod.v1.RunnerService/UpdateRunner

UpdateRunner updates an environment runner.

Runners

Configurations

runners.configurations

Methods

Validate Runner Configuration -> { environmentClass } | { scmIntegration }

post/gitpod.v1.RunnerConfigurationService/ValidateRunnerConfiguration

ValidateRunnerConfiguration validates a runner configuration (e.g. environment class, SCM integration) with the runner.

Runners Configurations

Environment Classes

runners.configurations.environment_classes

Methods

Create Environment Class -> { id }

post/gitpod.v1.RunnerConfigurationService/CreateEnvironmentClass

CreateEnvironmentClass creates a new environment class on a runner.

List Environment Classes -> EnvironmentClassesPage<{ id, configuration, description, 3 more... }>

post/gitpod.v1.RunnerConfigurationService/ListEnvironmentClasses

ListEnvironmentClasses returns all environment classes configured for a runner. buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE

Get Environment Class -> { environmentClass }

post/gitpod.v1.RunnerConfigurationService/GetEnvironmentClass

GetEnvironmentClass returns a single environment class configured for a runner.

Update Environment Class -> unknown

post/gitpod.v1.RunnerConfigurationService/UpdateEnvironmentClass

UpdateEnvironmentClass updates an existing environment class on a runner.

Runners Configurations

Host Authentication Tokens

runners.configurations.host_authentication_tokens

Methods

Create Host Authentication Token -> { token }

post/gitpod.v1.RunnerConfigurationService/CreateHostAuthenticationToken

CreateHostAuthenticationToken

Delete Host Authentication Token -> unknown

post/gitpod.v1.RunnerConfigurationService/DeleteHostAuthenticationToken

DeleteHostAuthenticationToken

List Host Authentication Tokens -> TokensPage<{ id, expiresAt, host, 3 more... }>

post/gitpod.v1.RunnerConfigurationService/ListHostAuthenticationTokens

ListHostAuthenticationTokens

Get Host Authentication Token -> { token }

post/gitpod.v1.RunnerConfigurationService/GetHostAuthenticationToken

GetHostAuthenticationToken

Update Host Authentication Token -> unknown

post/gitpod.v1.RunnerConfigurationService/UpdateHostAuthenticationToken

UpdateHostAuthenticationToken

Runners Configurations

Schema

runners.configurations.schema

Methods

Get Runner Configuration Schema -> { schema }

post/gitpod.v1.RunnerConfigurationService/GetRunnerConfigurationSchema

GetRunnerConfigurationSchema retrieves the latest Runner configuration schema

Runners Configurations

Scm Integrations

runners.configurations.scm_integrations

Methods

Create Scm Integration -> { id }

post/gitpod.v1.RunnerConfigurationService/CreateSCMIntegration

CreateSCMIntegration creates a new SCM integration on a runner.

Delete Scm Integration -> unknown

post/gitpod.v1.RunnerConfigurationService/DeleteSCMIntegration

DeleteSCMIntegration deletes an existing SCM integration on a runner.

List Scm Integrations -> IntegrationsPage<{ oauth, id, host, 3 more... }>

post/gitpod.v1.RunnerConfigurationService/ListSCMIntegrations

ListSCMIntegrations returns all SCM integrations configured for a runner.

Get Scm Integration -> { integration }

post/gitpod.v1.RunnerConfigurationService/GetSCMIntegration

GetSCMIntegration returns a single SCM integration configured for a runner.

Update Scm Integration -> unknown

post/gitpod.v1.RunnerConfigurationService/UpdateSCMIntegration

UpdateSCMIntegration updates an existing SCM integration on a runner.

Runners

Policies

runners.policies

Methods

Create Runner Policy -> { policy }

post/gitpod.v1.RunnerService/CreateRunnerPolicy

CreateRunnerPolicy creates a new runner policy.

Delete Runner Policy -> unknown

post/gitpod.v1.RunnerService/DeleteRunnerPolicy

DeleteRunnerPolicy deletes a runner policy.

List Runner Policies -> PoliciesPage<{ groupId, role }>

post/gitpod.v1.RunnerService/ListRunnerPolicies

ListRunnerPolicies lists runner policies.

Update Runner Policy -> { policy }

post/gitpod.v1.RunnerService/UpdateRunnerPolicy

UpdateRunnerPolicy an existing runner policy.