Skip to content
Ona API Reference
Ona Docs
API Reference
Runners
Configurations

ValidateRunnerConfiguration

runners.configurations.validate(ConfigurationValidateParams**kwargs) -> ConfigurationValidateResponse
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
environment_class: Optional[EnvironmentClass]
id: str

id is the unique identifier of the environment class

runner_id: str

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

configuration: Optional[List[FieldValue]]

configuration describes the configuration of the environment class

key: Optional[str]
value: Optional[str]
description: Optional[str]

description is a human readable description of the environment class

maxLength200
minLength3
display_name: Optional[str]

display_name is the human readable name of the environment class

maxLength127
minLength3
enabled: Optional[bool]

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

runner_id: Optional[str]
formatuuid
scm_integration: Optional[ScmIntegration]
id: Optional[str]

id is the unique identifier of the SCM integration

host: Optional[str]
issuer_url: Optional[str]

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

oauth_client_id: Optional[str]

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

oauth_encrypted_client_secret: Optional[Union[str, Base64FileInput]]

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
oauth_plaintext_client_secret: Optional[str]

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: Optional[bool]
scm_id: Optional[str]

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

virtual_directory: Optional[str]

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
class ConfigurationValidateResponse: …
environment_class: Optional[EnvironmentClassValidationResult]
configuration_errors: Optional[List[FieldValidationError]]
error: Optional[str]
key: Optional[str]
description_error: Optional[str]
display_name_error: Optional[str]
valid: Optional[bool]
scm_integration: Optional[ScmIntegrationValidationResult]
host_error: Optional[str]
oauth_error: Optional[str]
pat_error: Optional[str]
scm_id_error: Optional[str]
valid: Optional[bool]

ValidateRunnerConfiguration

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
response = client.runners.configurations.validate(
    runner_id="d2c94c27-3b76-4a42-b88c-95a85e392c68",
    scm_integration={
        "host": "github.com",
        "id": "integration-id",
        "oauth_client_id": "client_id",
        "oauth_plaintext_client_secret": "client_secret",
        "scm_id": "github",
    },
)
print(response.environment_class)
{
  "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
  }
}