Skip to content
Ona API Reference
Ona Docs
API Reference
Runners

CreateRunner

runners.create(RunnerCreateParams**kwargs) -> RunnerCreateResponse
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
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[str]

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"
runner_manager_id: Optional[str]

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[RunnerSpecParam]
configuration: Optional[RunnerConfiguration]

The runner’s configuration

auto_update: Optional[bool]

auto_update indicates whether the runner should automatically update itself.

devcontainer_image_cache_enabled: Optional[bool]

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.

log_level: 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]

metrics contains configuration for the runner’s metrics collection

enabled: Optional[bool]

enabled indicates whether the runner should collect metrics

managed_metrics_enabled: Optional[bool]

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

password: Optional[str]

password is the password to use for the metrics collector

url: Optional[str]

url is the URL of the metrics collector

username: Optional[str]

username is the username to use for the metrics collector

region: Optional[str]

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.

release_channel: 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"
update_window: Optional[UpdateWindow]

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

end_hour: Optional[int]

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

start_hour: Optional[int]

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

desired_phase: 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
class RunnerCreateResponse: …
runner: Runner
created_at: Optional[datetime]

Time when the Runner was created.

formatdate-time
creator: Optional[Subject]

creator is the identity of the creator of the environment

id: Optional[str]

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[str]

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"
runner_id: Optional[str]
runner_manager_id: Optional[str]

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

formatuuid
spec: Optional[RunnerSpec]

The runner’s specification

configuration: Optional[RunnerConfiguration]

The runner’s configuration

auto_update: Optional[bool]

auto_update indicates whether the runner should automatically update itself.

devcontainer_image_cache_enabled: Optional[bool]

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.

log_level: 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]

metrics contains configuration for the runner’s metrics collection

enabled: Optional[bool]

enabled indicates whether the runner should collect metrics

managed_metrics_enabled: Optional[bool]

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

password: Optional[str]

password is the password to use for the metrics collector

url: Optional[str]

url is the URL of the metrics collector

username: Optional[str]

username is the username to use for the metrics collector

region: Optional[str]

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.

release_channel: 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"
update_window: Optional[UpdateWindow]

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

end_hour: Optional[int]

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

start_hour: Optional[int]

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

desired_phase: 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]

The runner’s status

additional_info: Optional[List[FieldValue]]

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

key: Optional[str]
value: Optional[str]
capabilities: Optional[List[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"
gateway_info: Optional[GatewayInfo]

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

gateway: Optional[Gateway]

Gateway represents a system gateway that provides access to services

name: str

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

url: str

url of the gateway

region: Optional[str]

region is the geographical region where the gateway is located

latency: Optional[str]

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

formatregex
llm_url: Optional[str]

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

log_url: Optional[str]
message: Optional[str]

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"
public_key: Optional[str]

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

formatbyte
maxLength32
minLength32
region: Optional[str]

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

support_bundle_url: Optional[str]

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.

system_details: Optional[str]
updated_at: Optional[datetime]

Time when the status was last updated.

formatdate-time
version: Optional[str]
updated_at: Optional[datetime]

Time when the Runner was last udpated.

formatdate-time
Deprecatedaccess_token: Optional[str]

deprecated, will be removed. Use exchange_token instead.

exchange_token: Optional[str]

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 os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
runner = client.runners.create(
    name="Production Runner",
    provider="RUNNER_PROVIDER_AWS_EC2",
    spec={
        "configuration": {
            "auto_update": True,
            "region": "us-west",
            "release_channel": "RUNNER_RELEASE_CHANNEL_STABLE",
        },
        "desired_phase": "RUNNER_PHASE_ACTIVE",
    },
)
print(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"
}