## 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. ```yaml 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. ```yaml name: "Local Development Runner" provider: RUNNER_PROVIDER_LINUX_HOST spec: desiredPhase: RUNNER_PHASE_ACTIVE configuration: releaseChannel: RUNNER_RELEASE_CHANNEL_LATEST autoUpdate: true ``` ### Parameters - `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. - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `name: Optional[str]` The runner name for humans - `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) - `"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. - `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 - `"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 - `"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 - `"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 - `"RUNNER_VARIANT_UNSPECIFIED"` - `"RUNNER_VARIANT_STANDARD"` - `"RUNNER_VARIANT_ENTERPRISE"` ### Returns - `class RunnerCreateResponse: …` - `runner: Runner` - `created_at: Optional[datetime]` Time when the Runner was created. - `creator: Optional[Subject]` creator is the identity of the creator of the environment - `id: Optional[str]` id is the UUID of the subject - `principal: Optional[Principal]` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `kind: Optional[RunnerKind]` The runner's kind - `"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 - `"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. - `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 - `"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 - `"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 - `"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 - `"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. - `"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. - `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 - `public_key: Optional[str]` public_key is the runner's public key used for encryption (32 bytes) - `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. - `version: Optional[str]` - `updated_at: Optional[datetime]` Time when the Runner was last udpated. - `access_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. ### Example ```python 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) ``` #### Response ```json { "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" } ```