Skip to content
Ona API Reference
Ona Docs
API Reference
Runners

CreateRunner

client.runners.create(RunnerCreateParams { kind, name, provider, 2 more } body, RequestOptionsoptions?): RunnerCreateResponse { 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
ParametersExpand Collapse
body: RunnerCreateParams { kind, name, provider, 2 more }
kind?: 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.

One of the following:
"RUNNER_KIND_UNSPECIFIED"
"RUNNER_KIND_LOCAL"
"RUNNER_KIND_REMOTE"
"RUNNER_KIND_LOCAL_CONFIGURATION"
name?: string

The runner name for humans

maxLength127
minLength3
provider?: 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)

One of the following:
"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"
runnerManagerId?: string

The runner manager id specifies the runner manager for the managed runner. This field is mandatory for managed runners, otheriwse should not be set.

formatuuid
spec?: RunnerSpec { configuration, desiredPhase, variant }
configuration?: RunnerConfiguration { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more }

The runner’s configuration

autoUpdate?: boolean

auto_update indicates whether the runner should automatically update itself.

devcontainerImageCacheEnabled?: boolean

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.

logLevel?: LogLevel

log_level is the log level for the runner

One of the following:
"LOG_LEVEL_UNSPECIFIED"
"LOG_LEVEL_DEBUG"
"LOG_LEVEL_INFO"
"LOG_LEVEL_WARN"
"LOG_LEVEL_ERROR"
metrics?: MetricsConfiguration { enabled, managedMetricsEnabled, password, 2 more }

metrics contains configuration for the runner’s metrics collection

enabled?: boolean

enabled indicates whether the runner should collect metrics

managedMetricsEnabled?: boolean

When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint.

password?: string

password is the password to use for the metrics collector

url?: string

url is the URL of the metrics collector

username?: string

username is the username to use for the metrics collector

region?: string

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.

releaseChannel?: RunnerReleaseChannel

The release channel the runner is on

One of the following:
"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"
"RUNNER_RELEASE_CHANNEL_STABLE"
"RUNNER_RELEASE_CHANNEL_LATEST"
updateWindow?: UpdateWindow { endHour, startHour }

update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time.

endHour?: number | null

end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2.

startHour?: number | null

start_hour is the beginning of the update window as a UTC hour (0-23). +required

desiredPhase?: RunnerPhase

RunnerPhase represents the phase a runner is in

One of the following:
"RUNNER_PHASE_UNSPECIFIED"
"RUNNER_PHASE_CREATED"
"RUNNER_PHASE_INACTIVE"
"RUNNER_PHASE_ACTIVE"
"RUNNER_PHASE_DELETING"
"RUNNER_PHASE_DELETED"
"RUNNER_PHASE_DEGRADED"
variant?: RunnerVariant

The runner’s variant

One of the following:
"RUNNER_VARIANT_UNSPECIFIED"
"RUNNER_VARIANT_STANDARD"
"RUNNER_VARIANT_ENTERPRISE"
ReturnsExpand Collapse
RunnerCreateResponse { runner, accessToken, exchangeToken }
runner: Runner { createdAt, creator, kind, 7 more }
createdAt?: string

Time when the Runner was created.

formatdate-time
creator?: Subject { id, principal }

creator is the identity of the creator of the environment

id?: string

id is the UUID of the subject

formatuuid
principal?: Principal

Principal is the principal of the subject

One of the following:
"PRINCIPAL_UNSPECIFIED"
"PRINCIPAL_ACCOUNT"
"PRINCIPAL_USER"
"PRINCIPAL_RUNNER"
"PRINCIPAL_ENVIRONMENT"
"PRINCIPAL_SERVICE_ACCOUNT"
"PRINCIPAL_RUNNER_MANAGER"
kind?: RunnerKind

The runner’s kind

One of the following:
"RUNNER_KIND_UNSPECIFIED"
"RUNNER_KIND_LOCAL"
"RUNNER_KIND_REMOTE"
"RUNNER_KIND_LOCAL_CONFIGURATION"
name?: string

The runner’s name which is shown to users

provider?: RunnerProvider

The runner’s provider

One of the following:
"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"
runnerId?: string
runnerManagerId?: string

The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners.

formatuuid
spec?: RunnerSpec { configuration, desiredPhase, variant }

The runner’s specification

configuration?: RunnerConfiguration { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more }

The runner’s configuration

autoUpdate?: boolean

auto_update indicates whether the runner should automatically update itself.

devcontainerImageCacheEnabled?: boolean

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.

logLevel?: LogLevel

log_level is the log level for the runner

One of the following:
"LOG_LEVEL_UNSPECIFIED"
"LOG_LEVEL_DEBUG"
"LOG_LEVEL_INFO"
"LOG_LEVEL_WARN"
"LOG_LEVEL_ERROR"
metrics?: MetricsConfiguration { enabled, managedMetricsEnabled, password, 2 more }

metrics contains configuration for the runner’s metrics collection

enabled?: boolean

enabled indicates whether the runner should collect metrics

managedMetricsEnabled?: boolean

When true, the runner pushes metrics to the management plane via ReportRunnerMetrics instead of directly to the remote_write endpoint.

password?: string

password is the password to use for the metrics collector

url?: string

url is the URL of the metrics collector

username?: string

username is the username to use for the metrics collector

region?: string

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.

releaseChannel?: RunnerReleaseChannel

The release channel the runner is on

One of the following:
"RUNNER_RELEASE_CHANNEL_UNSPECIFIED"
"RUNNER_RELEASE_CHANNEL_STABLE"
"RUNNER_RELEASE_CHANNEL_LATEST"
updateWindow?: UpdateWindow { endHour, startHour }

update_window defines the daily time window (UTC) during which auto-updates are allowed. If not set, updates are allowed at any time.

endHour?: number | null

end_hour is the end of the update window as a UTC hour (0-23). If not set, defaults to start_hour + 2.

startHour?: number | null

start_hour is the beginning of the update window as a UTC hour (0-23). +required

desiredPhase?: RunnerPhase

RunnerPhase represents the phase a runner is in

One of the following:
"RUNNER_PHASE_UNSPECIFIED"
"RUNNER_PHASE_CREATED"
"RUNNER_PHASE_INACTIVE"
"RUNNER_PHASE_ACTIVE"
"RUNNER_PHASE_DELETING"
"RUNNER_PHASE_DELETED"
"RUNNER_PHASE_DEGRADED"
variant?: RunnerVariant

The runner’s variant

One of the following:
"RUNNER_VARIANT_UNSPECIFIED"
"RUNNER_VARIANT_STANDARD"
"RUNNER_VARIANT_ENTERPRISE"
status?: RunnerStatus { additionalInfo, capabilities, gatewayInfo, 10 more }

The runner’s status

additionalInfo?: Array<FieldValue { key, value } >

additional_info contains additional information about the runner, e.g. a CloudFormation stack URL.

key?: string
value?: string
capabilities?: Array<RunnerCapability>

capabilities is a list of capabilities the runner supports.

One of the following:
"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"
gatewayInfo?: GatewayInfo { gateway, latency }

gateway_info is information about the gateway to which the runner is connected.

gateway?: Gateway { name, url, region }

Gateway represents a system gateway that provides access to services

name: string

name is the human-readable name of the gateway. name is unique across all gateways.

url: string

url of the gateway

region?: string

region is the geographical region where the gateway is located

latency?: string

latency is the round-trip time of the runner to the gateway in milliseconds.

formatregex
llmUrl?: string

llm_url is the URL of the LLM service to which the runner is connected.

logUrl?: string
message?: string

The runner’s reported message which is shown to users. This message adds more context to the runner’s phase.

phase?: RunnerPhase

The runner’s reported phase

One of the following:
"RUNNER_PHASE_UNSPECIFIED"
"RUNNER_PHASE_CREATED"
"RUNNER_PHASE_INACTIVE"
"RUNNER_PHASE_ACTIVE"
"RUNNER_PHASE_DELETING"
"RUNNER_PHASE_DELETED"
"RUNNER_PHASE_DEGRADED"
publicKey?: string

public_key is the runner’s public key used for encryption (32 bytes)

formatbyte
maxLength32
minLength32
region?: string

region is the region the runner is running in, if applicable.

supportBundleUrl?: string

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.

systemDetails?: string
updatedAt?: string

Time when the status was last updated.

formatdate-time
version?: string
updatedAt?: string

Time when the Runner was last udpated.

formatdate-time
DeprecatedaccessToken?: string

deprecated, will be removed. Use exchange_token instead.

exchangeToken?: string

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.

CreateRunner

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

const runner = await client.runners.create({
  name: 'Production Runner',
  provider: 'RUNNER_PROVIDER_AWS_EC2',
  spec: {
    configuration: {
      autoUpdate: true,
      region: 'us-west',
      releaseChannel: 'RUNNER_RELEASE_CHANNEL_STABLE',
    },
    desiredPhase: 'RUNNER_PHASE_ACTIVE',
  },
});

console.log(runner.runner);
{
  "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"
}
Returns Examples
{
  "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"
}