## 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.

  ```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

- `body RunnerNewParams`

  - `Kind param.Field[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.

  - `Name param.Field[string]`

    The runner name for humans

  - `Provider param.Field[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)

  - `RunnerManagerID param.Field[string]`

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

### Returns

- `type RunnerNewResponse struct{…}`

  - `Runner Runner`

    - `CreatedAt Time`

      Time when the Runner was created.

    - `Creator Subject`

      creator is the identity of the creator of the environment

      - `ID string`

        id is the UUID of the subject

      - `Principal Principal`

        Principal is the principal of the subject

        - `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 RunnerKind`

      The runner's kind

      - `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 string`

      The runner's name which is shown to users

    - `Provider RunnerProvider`

      The runner's provider

      - `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 string`

    - `RunnerManagerID string`

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

    - `Spec RunnerSpec`

      The runner's specification

      - `Configuration RunnerConfiguration`

        The runner's configuration

        - `AutoUpdate bool`

          auto_update indicates whether the runner should automatically update itself.

        - `DevcontainerImageCacheEnabled 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.

        - `LogLevel LogLevel`

          log_level is the log level for the runner

          - `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 MetricsConfiguration`

          metrics contains configuration for the runner's metrics collection

          - `Enabled bool`

            enabled indicates whether the runner should collect metrics

          - `ManagedMetricsEnabled bool`

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

          - `Password string`

            password is the password to use for the metrics collector

          - `URL string`

            url is the URL of the metrics collector

          - `Username string`

            username is the username to use for the metrics collector

        - `Region string`

          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 RunnerReleaseChannel`

          The release channel the runner is on

          - `const RunnerReleaseChannelUnspecified RunnerReleaseChannel = "RUNNER_RELEASE_CHANNEL_UNSPECIFIED"`

          - `const RunnerReleaseChannelStable RunnerReleaseChannel = "RUNNER_RELEASE_CHANNEL_STABLE"`

          - `const RunnerReleaseChannelLatest RunnerReleaseChannel = "RUNNER_RELEASE_CHANNEL_LATEST"`

        - `UpdateWindow UpdateWindow`

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

          - `EndHour int64`

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

          - `StartHour int64`

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

      - `DesiredPhase RunnerPhase`

        RunnerPhase represents the phase a runner is in

        - `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 RunnerVariant`

        The runner's variant

        - `const RunnerVariantUnspecified RunnerVariant = "RUNNER_VARIANT_UNSPECIFIED"`

        - `const RunnerVariantStandard RunnerVariant = "RUNNER_VARIANT_STANDARD"`

        - `const RunnerVariantEnterprise RunnerVariant = "RUNNER_VARIANT_ENTERPRISE"`

    - `Status RunnerStatus`

      The runner's status

      - `AdditionalInfo []FieldValue`

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

        - `Key string`

        - `Value string`

      - `Capabilities []RunnerCapability`

        capabilities is a list of capabilities the runner supports.

        - `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 GatewayInfo`

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

        - `Gateway Gateway`

          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 string`

            region is the geographical region where the gateway is located

        - `Latency string`

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

      - `LlmURL string`

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

      - `LogURL string`

      - `Message string`

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

      - `Phase RunnerPhase`

        The runner's reported phase

      - `PublicKey string`

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

      - `Region string`

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

      - `SupportBundleURL string`

        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 string`

      - `UpdatedAt Time`

        Time when the status was last updated.

      - `Version string`

    - `UpdatedAt Time`

      Time when the Runner was last udpated.

  - `AccessToken string`

    deprecated, will be removed. Use exchange_token instead.

  - `ExchangeToken string`

    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

```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.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)
}
```

#### 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"
}
```