API Reference

Runners

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

GetRunner

client.Runners.Get(ctx, body) (*RunnerGetResponse, error)

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 RunnerGetParams

RunnerID param.Field[string]Optional

formatuuid

ReturnsExpand Collapse

type RunnerGetResponse struct{…}

Runner Runner

CreatedAt TimeOptional

Time when the Runner was created.

formatdate-time

Creator SubjectOptional

creator is the identity of the creator of the environment

ID stringOptional

id is the UUID of the subject

formatuuid

Principal PrincipalOptional

Principal is the principal of the subject

One of the following:

const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"

const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"

const PrincipalUser Principal = "PRINCIPAL_USER"

const PrincipalRunner Principal = "PRINCIPAL_RUNNER"

const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"

const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"

const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"

Kind RunnerKindOptional

The runner’s kind

One of the following:

const RunnerKindUnspecified RunnerKind = "RUNNER_KIND_UNSPECIFIED"

const RunnerKindLocal RunnerKind = "RUNNER_KIND_LOCAL"

const RunnerKindRemote RunnerKind = "RUNNER_KIND_REMOTE"

const RunnerKindLocalConfiguration RunnerKind = "RUNNER_KIND_LOCAL_CONFIGURATION"

Name stringOptional

The runner’s name which is shown to users

Provider RunnerProviderOptional

The runner’s provider

One of the following:

const RunnerProviderUnspecified RunnerProvider = "RUNNER_PROVIDER_UNSPECIFIED"

const RunnerProviderAwsEc2 RunnerProvider = "RUNNER_PROVIDER_AWS_EC2"

const RunnerProviderLinuxHost RunnerProvider = "RUNNER_PROVIDER_LINUX_HOST"

const RunnerProviderDesktopMac RunnerProvider = "RUNNER_PROVIDER_DESKTOP_MAC"

const RunnerProviderManaged RunnerProvider = "RUNNER_PROVIDER_MANAGED"

const RunnerProviderGcp RunnerProvider = "RUNNER_PROVIDER_GCP"

const RunnerProviderDevAgent RunnerProvider = "RUNNER_PROVIDER_DEV_AGENT"

RunnerID stringOptional

RunnerManagerID stringOptional

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

formatuuid

Spec RunnerSpecOptional

The runner’s specification

Configuration RunnerConfigurationOptional

The runner’s configuration

AutoUpdate boolOptional

auto_update indicates whether the runner should automatically update itself.

DevcontainerImageCacheEnabled boolOptional

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 LogLevelOptional

log_level is the log level for the runner

One of the following:

const LogLevelUnspecified LogLevel = "LOG_LEVEL_UNSPECIFIED"

const LogLevelDebug LogLevel = "LOG_LEVEL_DEBUG"

const LogLevelInfo LogLevel = "LOG_LEVEL_INFO"

const LogLevelWarn LogLevel = "LOG_LEVEL_WARN"

const LogLevelError LogLevel = "LOG_LEVEL_ERROR"

Metrics MetricsConfigurationOptional

metrics contains configuration for the runner’s metrics collection

Enabled boolOptional

enabled indicates whether the runner should collect metrics

ManagedMetricsEnabled boolOptional

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

Password stringOptional

password is the password to use for the metrics collector

URL stringOptional

url is the URL of the metrics collector

Username stringOptional

username is the username to use for the metrics collector

Region stringOptional

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 RunnerReleaseChannelOptional

The release channel the runner is on

One of the following:

const RunnerReleaseChannelUnspecified RunnerReleaseChannel = "RUNNER_RELEASE_CHANNEL_UNSPECIFIED"

const RunnerReleaseChannelStable RunnerReleaseChannel = "RUNNER_RELEASE_CHANNEL_STABLE"

const RunnerReleaseChannelLatest RunnerReleaseChannel = "RUNNER_RELEASE_CHANNEL_LATEST"

UpdateWindow UpdateWindowOptional

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

EndHour int64Optional

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

StartHour int64Optional

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

DesiredPhase RunnerPhaseOptional

RunnerPhase represents the phase a runner is in

One of the following:

const RunnerPhaseUnspecified RunnerPhase = "RUNNER_PHASE_UNSPECIFIED"

const RunnerPhaseCreated RunnerPhase = "RUNNER_PHASE_CREATED"

const RunnerPhaseInactive RunnerPhase = "RUNNER_PHASE_INACTIVE"

const RunnerPhaseActive RunnerPhase = "RUNNER_PHASE_ACTIVE"

const RunnerPhaseDeleting RunnerPhase = "RUNNER_PHASE_DELETING"

const RunnerPhaseDeleted RunnerPhase = "RUNNER_PHASE_DELETED"

const RunnerPhaseDegraded RunnerPhase = "RUNNER_PHASE_DEGRADED"

Variant RunnerVariantOptional

The runner’s variant

One of the following:

const RunnerVariantUnspecified RunnerVariant = "RUNNER_VARIANT_UNSPECIFIED"

const RunnerVariantStandard RunnerVariant = "RUNNER_VARIANT_STANDARD"

const RunnerVariantEnterprise RunnerVariant = "RUNNER_VARIANT_ENTERPRISE"

Status RunnerStatusOptional

The runner’s status

AdditionalInfo []FieldValueOptional

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

Key stringOptional

Value stringOptional

Capabilities []RunnerCapabilityOptional

capabilities is a list of capabilities the runner supports.

One of the following:

const RunnerCapabilityUnspecified RunnerCapability = "RUNNER_CAPABILITY_UNSPECIFIED"

const RunnerCapabilityFetchLocalScmIntegrations RunnerCapability = "RUNNER_CAPABILITY_FETCH_LOCAL_SCM_INTEGRATIONS"

const RunnerCapabilitySecretContainerRegistry RunnerCapability = "RUNNER_CAPABILITY_SECRET_CONTAINER_REGISTRY"

const RunnerCapabilityAgentExecution RunnerCapability = "RUNNER_CAPABILITY_AGENT_EXECUTION"

const RunnerCapabilityAllowEnvTokenPopulation RunnerCapability = "RUNNER_CAPABILITY_ALLOW_ENV_TOKEN_POPULATION"

const RunnerCapabilityDefaultDevContainerImage RunnerCapability = "RUNNER_CAPABILITY_DEFAULT_DEV_CONTAINER_IMAGE"

const RunnerCapabilityEnvironmentSnapshot RunnerCapability = "RUNNER_CAPABILITY_ENVIRONMENT_SNAPSHOT"

const RunnerCapabilityPrebuildsBeforeSnapshotTrigger RunnerCapability = "RUNNER_CAPABILITY_PREBUILDS_BEFORE_SNAPSHOT_TRIGGER"

const RunnerCapabilityListScmOrganizations RunnerCapability = "RUNNER_CAPABILITY_LIST_SCM_ORGANIZATIONS"

const RunnerCapabilityCheckRepositoryAccess RunnerCapability = "RUNNER_CAPABILITY_CHECK_REPOSITORY_ACCESS"

const RunnerCapabilityRunnerSideAgent RunnerCapability = "RUNNER_CAPABILITY_RUNNER_SIDE_AGENT"

const RunnerCapabilityWarmPool RunnerCapability = "RUNNER_CAPABILITY_WARM_POOL"

const RunnerCapabilityAsgWarmPool RunnerCapability = "RUNNER_CAPABILITY_ASG_WARM_POOL"

const RunnerCapabilityPortAuthentication RunnerCapability = "RUNNER_CAPABILITY_PORT_AUTHENTICATION"

GatewayInfo GatewayInfoOptional

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

Gateway GatewayOptional

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 stringOptional

region is the geographical region where the gateway is located

Latency stringOptional

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

formatregex

LlmURL stringOptional

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

LogURL stringOptional

Message stringOptional

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

Phase RunnerPhaseOptional

The runner’s reported phase

One of the following:

const RunnerPhaseUnspecified RunnerPhase = "RUNNER_PHASE_UNSPECIFIED"

const RunnerPhaseCreated RunnerPhase = "RUNNER_PHASE_CREATED"

const RunnerPhaseInactive RunnerPhase = "RUNNER_PHASE_INACTIVE"

const RunnerPhaseActive RunnerPhase = "RUNNER_PHASE_ACTIVE"

const RunnerPhaseDeleting RunnerPhase = "RUNNER_PHASE_DELETING"

const RunnerPhaseDeleted RunnerPhase = "RUNNER_PHASE_DELETED"

const RunnerPhaseDegraded RunnerPhase = "RUNNER_PHASE_DEGRADED"

PublicKey stringOptional

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

formatbyte

maxLength32

minLength32

Region stringOptional

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

SupportBundleURL stringOptional

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 stringOptional

UpdatedAt TimeOptional

Time when the status was last updated.

formatdate-time

Version stringOptional

UpdatedAt TimeOptional

Time when the Runner was last udpated.

formatdate-time

GetRunner

Go

HTTP

TypeScript

Python

Go

package main

import (
  "context"
  "fmt"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  runner, err := client.Runners.Get(context.TODO(), gitpod.RunnerGetParams{
    RunnerID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", runner.Runner)
}

200 example

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

200 example

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