ValidateRunnerConfiguration

client.runners.configurations.validate(, ?): ConfigurationValidateResponse { environmentClass, scmIntegration }

POST/gitpod.v1.RunnerConfigurationService/ValidateRunnerConfiguration

Validates a runner configuration.

Use this method to:

Check configuration validity
Verify integration settings
Validate environment classes

Examples

Validate SCM integration:

Checks if an SCM integration is valid.

runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
scmIntegration:
  id: "integration-id"
  scmId: "github"
  host: "github.com"
  oauthClientId: "client_id"
  oauthPlaintextClientSecret: "client_secret"

ParametersExpand Collapse

body: ConfigurationValidateParams { environmentClass, runnerId, scmIntegration }

environmentClass?: EnvironmentClass { id, runnerId, configuration, 3 more }

id: string

id is the unique identifier of the environment class

runnerId: string

runner_id is the unique identifier of the runner the environment class belongs to

configuration?: Array<FieldValue { key, value } >

configuration describes the configuration of the environment class

key?: string

value?: string

description?: string

description is a human readable description of the environment class

maxLength200

minLength3

displayName?: string

display_name is the human readable name of the environment class

maxLength127

minLength3

enabled?: boolean

enabled indicates whether the environment class can be used to create new environments.

runnerId?: string

formatuuid

scmIntegration?: ScmIntegration

id?: string

id is the unique identifier of the SCM integration

host?: string

issuerUrl?: string | null

issuer_url can be set to override the authentication provider URL, if it doesn’t match the SCM host.

oauthClientId?: string | null

oauth_client_id is the OAuth app’s client ID, if OAuth is configured. If configured, oauth_client_secret must also be set.

oauthEncryptedClientSecret?: string

oauth_encrypted_client_secret is the OAuth app’s client secret encrypted with the runner’s public key, if OAuth is configured. This can be used to e.g. validate an already encrypted client secret of an existing SCM integration.

formatbyte

oauthPlaintextClientSecret?: string

oauth_plaintext_client_secret is the OAuth app’s client secret in clear text, if OAuth is configured. This can be set to validate any new client secret before it is encrypted and stored. This value will not be stored and get encrypted with the runner’s public key before passing it to the runner.

pat?: boolean

scmId?: string

scm_id references the scm_id in the runner’s configuration schema that this integration is for

virtualDirectory?: string | null

virtual_directory is the virtual directory path for Azure DevOps Server (e.g., “/tfs”). This field is only used for Azure DevOps Server SCM integrations and should be empty for other SCM types. Azure DevOps Server APIs work without collection when PAT scope is ‘All accessible organizations’.

ReturnsExpand Collapse

ConfigurationValidateResponse { environmentClass, scmIntegration }

environmentClass?: EnvironmentClassValidationResult { configurationErrors, descriptionError, displayNameError, valid }

configurationErrors?: Array<FieldValidationError { error, key } >

error?: string

key?: string

descriptionError?: string | null

displayNameError?: string | null

valid?: boolean

scmIntegration?: ScmIntegrationValidationResult { hostError, oauthError, patError, 2 more }

hostError?: string | null

oauthError?: string | null

patError?: string | null

scmIdError?: string | null

valid?: boolean

ValidateRunnerConfiguration

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

const response = await client.runners.configurations.validate({
  runnerId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68',
  scmIntegration: {
    host: 'github.com',
    id: 'integration-id',
    oauthClientId: 'client_id',
    oauthPlaintextClientSecret: 'client_secret',
    scmId: 'github',
  },
});

console.log(response.environmentClass);

{
  "environmentClass": {
    "configurationErrors": [
      {
        "error": "error",
        "key": "key"
      }
    ],
    "descriptionError": "descriptionError",
    "displayNameError": "displayNameError",
    "valid": true
  },
  "scmIntegration": {
    "hostError": "hostError",
    "oauthError": "oauthError",
    "patError": "patError",
    "scmIdError": "scmIdError",
    "valid": true
  }
}

Returns Examples

{
  "environmentClass": {
    "configurationErrors": [
      {
        "error": "error",
        "key": "key"
      }
    ],
    "descriptionError": "descriptionError",
    "displayNameError": "displayNameError",
    "valid": true
  },
  "scmIntegration": {
    "hostError": "hostError",
    "oauthError": "oauthError",
    "patError": "patError",
    "scmIdError": "scmIdError",
    "valid": true
  }
}