Skip to content
Ona API Reference
Ona Docs
API Reference
Runners

GetRunner

client.runners.retrieve(RunnerRetrieveParams { runnerId } body, RequestOptionsoptions?): RunnerRetrieveResponse { 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"
ParametersExpand Collapse
body: RunnerRetrieveParams { runnerId }
runnerId?: string
formatuuid
ReturnsExpand Collapse
RunnerRetrieveResponse { runner }
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

GetRunner

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.retrieve({ runnerId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68' });

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