Skip to content
Ona API Reference
Ona Docs
API Reference
Runners

CreateRunner

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
Body ParametersJSONExpand Collapse
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.

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

The runner name for humans

maxLength127
minLength3
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)

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: optional 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: optional RunnerSpec { configuration, desiredPhase, variant }
configuration: optional RunnerConfiguration { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more }

The runner’s configuration

autoUpdate: optional boolean

auto_update indicates whether the runner should automatically update itself.

devcontainerImageCacheEnabled: optional 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: optional 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: optional MetricsConfiguration { enabled, managedMetricsEnabled, password, 2 more }

metrics contains configuration for the runner’s metrics collection

enabled: optional boolean

enabled indicates whether the runner should collect metrics

managedMetricsEnabled: optional boolean

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

password: optional string

password is the password to use for the metrics collector

url: optional string

url is the URL of the metrics collector

username: optional string

username is the username to use for the metrics collector

region: optional 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: optional 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: optional 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: optional number

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

startHour: optional number

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

desiredPhase: optional 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: optional RunnerVariant

The runner’s variant

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

Time when the Runner was created.

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

creator is the identity of the creator of the environment

id: optional string

id is the UUID of the subject

formatuuid
principal: optional 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: optional RunnerKind

The runner’s kind

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

The runner’s name which is shown to users

provider: optional 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: optional string
runnerManagerId: optional string

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

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

The runner’s specification

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

The runner’s configuration

autoUpdate: optional boolean

auto_update indicates whether the runner should automatically update itself.

devcontainerImageCacheEnabled: optional 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: optional 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: optional MetricsConfiguration { enabled, managedMetricsEnabled, password, 2 more }

metrics contains configuration for the runner’s metrics collection

enabled: optional boolean

enabled indicates whether the runner should collect metrics

managedMetricsEnabled: optional boolean

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

password: optional string

password is the password to use for the metrics collector

url: optional string

url is the URL of the metrics collector

username: optional string

username is the username to use for the metrics collector

region: optional 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: optional 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: optional 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: optional number

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

startHour: optional number

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

desiredPhase: optional 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: optional RunnerVariant

The runner’s variant

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

The runner’s status

additionalInfo: optional array of FieldValue { key, value }

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

key: optional string
value: optional string
capabilities: optional array of 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: optional GatewayInfo { gateway, latency }

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

gateway: optional 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: optional string

region is the geographical region where the gateway is located

latency: optional string

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

formatregex
llmUrl: optional string

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

logUrl: optional string
message: optional string

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

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: optional string

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

formatbyte
maxLength32
minLength32
region: optional string

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

supportBundleUrl: optional 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: optional string
updatedAt: optional string

Time when the status was last updated.

formatdate-time
version: optional string
updatedAt: optional string

Time when the Runner was last udpated.

formatdate-time
DeprecatedaccessToken: optional string

deprecated, will be removed. Use exchange_token instead.

exchangeToken: optional 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

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