CreateRunner

client.Runners.New(ctx, body) (*RunnerNewResponse, error)

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

body RunnerNewParams

Kind param.Field[RunnerKind]Optional

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.

Name param.Field[string]Optional

The runner name for humans

maxLength127

minLength3

Provider param.Field[RunnerProvider]Optional

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)

RunnerManagerID param.Field[string]Optional

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 param.Field[RunnerSpec]Optional

ReturnsExpand Collapse

type RunnerNewResponse 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

DeprecatedAccessToken stringOptional

deprecated, will be removed. Use exchange_token instead.

ExchangeToken stringOptional

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

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.New(context.TODO(), gitpod.RunnerNewParams{
    Name: gitpod.F("Production Runner"),
    Provider: gitpod.F(gitpod.RunnerProviderAwsEc2),
    Spec: gitpod.F(gitpod.RunnerSpecParam{
      Configuration: gitpod.F(gitpod.RunnerConfigurationParam{
        AutoUpdate: gitpod.F(true),
        Region: gitpod.F("us-west"),
        ReleaseChannel: gitpod.F(gitpod.RunnerReleaseChannelStable),
      }),
      DesiredPhase: gitpod.F(gitpod.RunnerPhaseActive),
    }),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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"
}