Skip to content
Ona API Reference
Ona Docs
API Reference
Runners

UpdateRunner

runners.update(RunnerUpdateParams**kwargs) -> object
POST/gitpod.v1.RunnerService/UpdateRunner

Updates a runner’s configuration.

Use this method to:

  • Modify runner settings
  • Update release channels
  • Change runner status
  • Configure auto-update settings

Examples

  • Update configuration:

    Changes runner settings.

    runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
name: "Updated Runner Name"
spec:
  configuration:
    releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST
    autoUpdate: true
ParametersExpand Collapse
name: Optional[str]

The runner’s name which is shown to users

maxLength127
minLength3
runner_id: Optional[str]

runner_id specifies which runner to be updated.

+required

formatuuid
spec: Optional[Spec]
configuration: Optional[SpecConfiguration]
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 shared devcontainer build cache is enabled for this runner.

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

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

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

update_window defines the daily time window (UTC) during which auto-updates are allowed. start_hour is required. If end_hour is omitted, it defaults to start_hour + 2. Send an empty UpdateWindow (no start_hour or end_hour) to clear a custom window and allow updates 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]

desired_phase can currently only be updated on local-configuration runners, to toggle whether local runners are allowed for running environments in the organization. Set to:

  • ACTIVE to enable local runners.
  • INACTIVE to disable all local runners. Existing local runners and their environments will stop, and cannot be started again until the desired_phase is set to ACTIVE. Use this carefully, as it will affect all users in the organization who use local runners.
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"
ReturnsExpand Collapse
object

UpdateRunner

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.update(
    name="Updated Runner Name",
    runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68",
    spec={
        "configuration": {
            "auto_update": True,
            "release_channel": "RUNNER_RELEASE_CHANNEL_LATEST",
        }
    },
)
print(runner)
{}
Returns Examples
{}