# Configurations ## ValidateRunnerConfiguration **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. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" scmIntegration: id: "integration-id" scmId: "github" host: "github.com" oauthClientId: "client_id" oauthPlaintextClientSecret: "client_secret" ``` ### Body Parameters - `environmentClass: optional EnvironmentClass` - `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: optional array of FieldValue` configuration describes the configuration of the environment class - `key: optional string` - `value: optional string` - `description: optional string` description is a human readable description of the environment class - `displayName: optional string` display_name is the human readable name of the environment class - `enabled: optional boolean` enabled indicates whether the environment class can be used to create new environments. - `runnerId: optional string` - `scmIntegration: optional object { id, host, issuerUrl, 6 more }` - `id: optional string` id is the unique identifier of the SCM integration - `host: optional string` - `issuerUrl: optional string` issuer_url can be set to override the authentication provider URL, if it doesn't match the SCM host. - `oauthClientId: optional string` oauth_client_id is the OAuth app's client ID, if OAuth is configured. If configured, oauth_client_secret must also be set. - `oauthEncryptedClientSecret: optional 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. - `oauthPlaintextClientSecret: optional 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: optional boolean` - `scmId: optional string` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtualDirectory: optional string` 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'. ### Returns - `environmentClass: optional EnvironmentClassValidationResult` - `configurationErrors: optional array of FieldValidationError` - `error: optional string` - `key: optional string` - `descriptionError: optional string` - `displayNameError: optional string` - `valid: optional boolean` - `scmIntegration: optional ScmIntegrationValidationResult` - `hostError: optional string` - `oauthError: optional string` - `patError: optional string` - `scmIdError: optional string` - `valid: optional boolean` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/ValidateRunnerConfiguration \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "environmentClass": { "configurationErrors": [ { "error": "error", "key": "key" } ], "descriptionError": "descriptionError", "displayNameError": "displayNameError", "valid": true }, "scmIntegration": { "hostError": "hostError", "oauthError": "oauthError", "patError": "patError", "scmIdError": "scmIdError", "valid": true } } ``` ## Domain Types ### Environment Class Validation Result - `EnvironmentClassValidationResult object { configurationErrors, descriptionError, displayNameError, valid }` - `configurationErrors: optional array of FieldValidationError` - `error: optional string` - `key: optional string` - `descriptionError: optional string` - `displayNameError: optional string` - `valid: optional boolean` ### Field Validation Error - `FieldValidationError object { error, key }` - `error: optional string` - `key: optional string` ### Scm Integration Validation Result - `ScmIntegrationValidationResult object { hostError, oauthError, patError, 2 more }` - `hostError: optional string` - `oauthError: optional string` - `patError: optional string` - `scmIdError: optional string` - `valid: optional boolean` ### Configuration Validate Response - `ConfigurationValidateResponse object { environmentClass, scmIntegration }` - `environmentClass: optional EnvironmentClassValidationResult` - `configurationErrors: optional array of FieldValidationError` - `error: optional string` - `key: optional string` - `descriptionError: optional string` - `displayNameError: optional string` - `valid: optional boolean` - `scmIntegration: optional ScmIntegrationValidationResult` - `hostError: optional string` - `oauthError: optional string` - `patError: optional string` - `scmIdError: optional string` - `valid: optional boolean` # Environment Classes ## CreateEnvironmentClass **post** `/gitpod.v1.RunnerConfigurationService/CreateEnvironmentClass` Creates a new environment class for a runner. Use this method to: - Define compute resources - Configure environment settings - Set up runtime options ### Examples - Create environment class: Creates a new environment configuration. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" displayName: "Large Instance" description: "8 CPU, 16GB RAM" configuration: - key: "cpu" value: "8" - key: "memory" value: "16384" ``` ### Body Parameters - `configuration: optional array of FieldValue` - `key: optional string` - `value: optional string` - `description: optional string` - `displayName: optional string` - `runnerId: optional string` ### Returns - `id: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/CreateEnvironmentClass \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "id" } ``` ## ListEnvironmentClasses **post** `/gitpod.v1.RunnerConfigurationService/ListEnvironmentClasses` Lists environment classes with optional filtering. Use this method to: - View available classes - Filter by capability - Check enabled status ### Examples - List all classes: Shows all environment classes. ```yaml pagination: pageSize: 20 ``` - Filter enabled classes: Lists only enabled environment classes. ```yaml filter: enabled: true pagination: pageSize: 20 ``` buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { canCreateEnvironments, enabled, runnerIds, 2 more }` - `canCreateEnvironments: optional boolean` can_create_environments filters the response to only environment classes that can be used to create new environments by the caller. Unlike enabled, which indicates general availability, this ensures the caller only sees environment classes they are allowed to use. - `enabled: optional boolean` enabled filters the response to only enabled or disabled environment classes. If not set, all environment classes are returned. - `runnerIds: optional array of string` runner_ids filters the response to only EnvironmentClasses of these Runner IDs - `runnerKinds: optional array of RunnerKind` runner_kind filters the response to only environment classes from runners of these kinds. - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `runnerProviders: optional array of RunnerProvider` runner_providers filters the response to only environment classes from runners of these providers. - `"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"` - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing environment classes - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `environmentClasses: optional array of EnvironmentClass` - `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: optional array of FieldValue` configuration describes the configuration of the environment class - `key: optional string` - `value: optional string` - `description: optional string` description is a human readable description of the environment class - `displayName: optional string` display_name is the human readable name of the environment class - `enabled: optional boolean` enabled indicates whether the environment class can be used to create new environments. - `pagination: optional object { nextToken }` pagination contains the pagination options for listing environment classes - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/ListEnvironmentClasses \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "environmentClasses": [ { "id": "id", "runnerId": "runnerId", "configuration": [ { "key": "key", "value": "value" } ], "description": "xxx", "displayName": "xxx", "enabled": true } ], "pagination": { "nextToken": "nextToken" } } ``` ## GetEnvironmentClass **post** `/gitpod.v1.RunnerConfigurationService/GetEnvironmentClass` Gets details about a specific environment class. Use this method to: - View class configuration - Check resource settings - Verify availability ### Examples - Get class details: Retrieves information about a specific class. ```yaml environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `environmentClassId: optional string` ### Returns - `environmentClass: optional EnvironmentClass` - `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: optional array of FieldValue` configuration describes the configuration of the environment class - `key: optional string` - `value: optional string` - `description: optional string` description is a human readable description of the environment class - `displayName: optional string` display_name is the human readable name of the environment class - `enabled: optional boolean` enabled indicates whether the environment class can be used to create new environments. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/GetEnvironmentClass \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "environmentClass": { "id": "id", "runnerId": "runnerId", "configuration": [ { "key": "key", "value": "value" } ], "description": "xxx", "displayName": "xxx", "enabled": true } } ``` ## UpdateEnvironmentClass **post** `/gitpod.v1.RunnerConfigurationService/UpdateEnvironmentClass` Updates an environment class. Use this method to: - Modify class settings - Update resource limits - Change availability ### Examples - Update class: Changes class configuration. ```yaml environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" displayName: "Updated Large Instance" description: "16 CPU, 32GB RAM" enabled: true ``` ### Body Parameters - `description: optional string` - `displayName: optional string` - `enabled: optional boolean` - `environmentClassId: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/UpdateEnvironmentClass \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## Domain Types ### Environment Class Create Response - `EnvironmentClassCreateResponse object { id }` - `id: optional string` ### Environment Class Retrieve Response - `EnvironmentClassRetrieveResponse object { environmentClass }` - `environmentClass: optional EnvironmentClass` - `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: optional array of FieldValue` configuration describes the configuration of the environment class - `key: optional string` - `value: optional string` - `description: optional string` description is a human readable description of the environment class - `displayName: optional string` display_name is the human readable name of the environment class - `enabled: optional boolean` enabled indicates whether the environment class can be used to create new environments. ### Environment Class Update Response - `EnvironmentClassUpdateResponse = unknown` # Host Authentication Tokens ## CreateHostAuthenticationToken **post** `/gitpod.v1.RunnerConfigurationService/CreateHostAuthenticationToken` Creates a new authentication token for accessing remote hosts. Use this method to: - Set up SCM authentication - Configure OAuth credentials - Manage PAT tokens ### Examples - Create OAuth token: Creates a new OAuth-based authentication token. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" userId: "f53d2330-3795-4c5d-a1f3-453121af9c60" host: "github.com" token: "gho_xxxxxxxxxxxx" source: HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH expiresAt: "2024-12-31T23:59:59Z" refreshToken: "ghr_xxxxxxxxxxxx" ``` ### Body Parameters - `token: optional string` stored encrypted, retrieved via GetHostAuthenticationTokenValue - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: optional string` - `integrationId: optional string` - `refreshToken: optional string` stored encrypted, retrieved via GetHostAuthenticationTokenValue - `runnerId: optional string` - `scopes: optional array of string` Maximum 100 scopes allowed (101 for validation purposes) - `source: optional HostAuthenticationTokenSource` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: optional Subject` Subject identifies the principal (user or service account) for the token - `id: optional string` 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"` - `userId: optional string` Deprecated: Use principal_id and principal_type instead ### Returns - `token: HostAuthenticationToken` - `id: string` - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: optional string` - `integrationId: optional string` links to integration instance - `runnerId: optional string` - `scopes: optional array of string` token permissions - `source: optional HostAuthenticationTokenSource` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: optional Subject` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: optional string` 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"` - `userId: optional string` Deprecated: Use principal_id and principal_type instead principal (user) ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/CreateHostAuthenticationToken \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "token": { "id": "id", "expiresAt": "2019-12-27T18:11:19.117Z", "host": "host", "integrationId": "integrationId", "runnerId": "runnerId", "scopes": [ "string" ], "source": "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED", "subject": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "userId": "userId" } } ``` ## DeleteHostAuthenticationToken **post** `/gitpod.v1.RunnerConfigurationService/DeleteHostAuthenticationToken` Deletes a host authentication token. Use this method to: - Remove unused tokens - Revoke access - Clean up expired tokens ### Examples - Delete token: Permanently removes a token. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/DeleteHostAuthenticationToken \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## ListHostAuthenticationTokens **post** `/gitpod.v1.RunnerConfigurationService/ListHostAuthenticationTokens` Lists host authentication tokens with optional filtering. Use this method to: - View all tokens - Filter by runner or user - Monitor token status ### Examples - List all tokens: Shows all tokens with pagination. ```yaml pagination: pageSize: 20 ``` - Filter by runner: Lists tokens for a specific runner. ```yaml filter: runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" pagination: pageSize: 20 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { runnerId, subjectId, userId }` - `runnerId: optional string` - `subjectId: optional string` Filter by subject (user or service account) - `userId: optional string` Deprecated: Use principal_id instead - `pagination: optional object { token, pageSize }` - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `pagination: optional object { nextToken }` - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results - `tokens: optional array of HostAuthenticationToken` - `id: string` - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: optional string` - `integrationId: optional string` links to integration instance - `runnerId: optional string` - `scopes: optional array of string` token permissions - `source: optional HostAuthenticationTokenSource` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: optional Subject` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: optional string` 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"` - `userId: optional string` Deprecated: Use principal_id and principal_type instead principal (user) ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/ListHostAuthenticationTokens \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "tokens": [ { "id": "id", "expiresAt": "2019-12-27T18:11:19.117Z", "host": "host", "integrationId": "integrationId", "runnerId": "runnerId", "scopes": [ "string" ], "source": "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED", "subject": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "userId": "userId" } ] } ``` ## GetHostAuthenticationToken **post** `/gitpod.v1.RunnerConfigurationService/GetHostAuthenticationToken` Gets details about a specific host authentication token. Use this method to: - View token information - Check token expiration - Verify token validity ### Examples - Get token details: Retrieves information about a specific token. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Returns - `token: HostAuthenticationToken` - `id: string` - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: optional string` - `integrationId: optional string` links to integration instance - `runnerId: optional string` - `scopes: optional array of string` token permissions - `source: optional HostAuthenticationTokenSource` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: optional Subject` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: optional string` 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"` - `userId: optional string` Deprecated: Use principal_id and principal_type instead principal (user) ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/GetHostAuthenticationToken \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "token": { "id": "id", "expiresAt": "2019-12-27T18:11:19.117Z", "host": "host", "integrationId": "integrationId", "runnerId": "runnerId", "scopes": [ "string" ], "source": "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED", "subject": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "userId": "userId" } } ``` ## UpdateHostAuthenticationToken **post** `/gitpod.v1.RunnerConfigurationService/UpdateHostAuthenticationToken` Updates an existing host authentication token. Use this method to: - Refresh token values - Update expiration - Modify token settings ### Examples - Update token: Updates token value and expiration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" token: "gho_xxxxxxxxxxxx" expiresAt: "2024-12-31T23:59:59Z" refreshToken: "ghr_xxxxxxxxxxxx" ``` ### Body Parameters - `id: optional string` - `token: optional string` - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `refreshToken: optional string` - `scopes: optional array of string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/UpdateHostAuthenticationToken \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## Domain Types ### Host Authentication Token - `HostAuthenticationToken object { id, expiresAt, host, 6 more }` - `id: string` - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: optional string` - `integrationId: optional string` links to integration instance - `runnerId: optional string` - `scopes: optional array of string` token permissions - `source: optional HostAuthenticationTokenSource` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: optional Subject` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: optional string` 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"` - `userId: optional string` Deprecated: Use principal_id and principal_type instead principal (user) ### Host Authentication Token Source - `HostAuthenticationTokenSource = "HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED" or "HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH" or "HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` ### Host Authentication Token Create Response - `HostAuthenticationTokenCreateResponse object { token }` - `token: HostAuthenticationToken` - `id: string` - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: optional string` - `integrationId: optional string` links to integration instance - `runnerId: optional string` - `scopes: optional array of string` token permissions - `source: optional HostAuthenticationTokenSource` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: optional Subject` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: optional string` 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"` - `userId: optional string` Deprecated: Use principal_id and principal_type instead principal (user) ### Host Authentication Token Delete Response - `HostAuthenticationTokenDeleteResponse = unknown` ### Host Authentication Token Retrieve Response - `HostAuthenticationTokenRetrieveResponse object { token }` - `token: HostAuthenticationToken` - `id: string` - `expiresAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `host: optional string` - `integrationId: optional string` links to integration instance - `runnerId: optional string` - `scopes: optional array of string` token permissions - `source: optional HostAuthenticationTokenSource` auth_type - `"HOST_AUTHENTICATION_TOKEN_SOURCE_UNSPECIFIED"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_OAUTH"` - `"HOST_AUTHENTICATION_TOKEN_SOURCE_PAT"` - `subject: optional Subject` Subject identifies the principal (user or service account) for the token Note: actual token and refresh_token values are retrieved via GetHostAuthenticationTokenValue API - `id: optional string` 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"` - `userId: optional string` Deprecated: Use principal_id and principal_type instead principal (user) ### Host Authentication Token Update Response - `HostAuthenticationTokenUpdateResponse = unknown` # Schema ## GetRunnerConfigurationSchema **post** `/gitpod.v1.RunnerConfigurationService/GetRunnerConfigurationSchema` Gets the latest runner configuration schema. Use this method to: - View available settings - Check configuration options - Validate configurations ### Examples - Get schema: Retrieves configuration schema for a runner. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `runnerId: optional string` ### Returns - `schema: optional RunnerConfigurationSchema` - `environmentClasses: optional array of object { id, bool, description, 7 more }` - `id: optional string` - `bool: optional object { default }` - `default: optional boolean` - `description: optional string` - `display: optional object { default }` - `default: optional string` - `enum: optional object { default, defaultValue, possibleValues, values }` - `default: optional string` deprecated, will be removed, use default_value instead - `defaultValue: optional object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `possibleValues: optional array of object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `values: optional array of string` deprecated, will be removed, use possible_values instead - `int: optional object { default, max, min }` - `default: optional number` - `max: optional number` - `min: optional number` - `name: optional string` - `required: optional boolean` - `secret: optional boolean` - `string: optional object { default, pattern }` - `default: optional string` - `pattern: optional string` - `runnerConfig: optional array of object { id, bool, description, 7 more }` - `id: optional string` - `bool: optional object { default }` - `default: optional boolean` - `description: optional string` - `display: optional object { default }` - `default: optional string` - `enum: optional object { default, defaultValue, possibleValues, values }` - `default: optional string` deprecated, will be removed, use default_value instead - `defaultValue: optional object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `possibleValues: optional array of object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `values: optional array of string` deprecated, will be removed, use possible_values instead - `int: optional object { default, max, min }` - `default: optional number` - `max: optional number` - `min: optional number` - `name: optional string` - `required: optional boolean` - `secret: optional boolean` - `string: optional object { default, pattern }` - `default: optional string` - `pattern: optional string` - `scm: optional array of object { defaultHosts, name, oauth, 2 more }` - `defaultHosts: optional array of string` - `name: optional string` - `oauth: optional object { callbackUrl }` - `callbackUrl: optional string` callback_url is the URL the OAuth app will redirect to after the user has authenticated. - `pat: optional object { description, docsLink }` - `description: optional string` description is a human-readable description of the PAT. - `docsLink: optional string` docs_link is a link to the documentation on how to create a PAT for this SCM system. - `scmId: optional string` - `version: optional string` The schema version ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/GetRunnerConfigurationSchema \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "schema": { "environmentClasses": [ { "id": "id", "bool": { "default": true }, "description": "description", "display": { "default": "default" }, "enum": { "default": "default", "defaultValue": { "detail": "detail", "subtitle": "subtitle", "title": "title" }, "possibleValues": [ { "detail": "detail", "subtitle": "subtitle", "title": "title" } ], "values": [ "string" ] }, "int": { "default": 0, "max": 0, "min": 0 }, "name": "name", "required": true, "secret": true, "string": { "default": "default", "pattern": "pattern" } } ], "runnerConfig": [ { "id": "id", "bool": { "default": true }, "description": "description", "display": { "default": "default" }, "enum": { "default": "default", "defaultValue": { "detail": "detail", "subtitle": "subtitle", "title": "title" }, "possibleValues": [ { "detail": "detail", "subtitle": "subtitle", "title": "title" } ], "values": [ "string" ] }, "int": { "default": 0, "max": 0, "min": 0 }, "name": "name", "required": true, "secret": true, "string": { "default": "default", "pattern": "pattern" } } ], "scm": [ { "defaultHosts": [ "string" ], "name": "name", "oauth": { "callbackUrl": "callbackUrl" }, "pat": { "description": "description", "docsLink": "docsLink" }, "scmId": "scmId" } ], "version": "version" } } ``` ## Domain Types ### Runner Configuration Schema - `RunnerConfigurationSchema object { environmentClasses, runnerConfig, scm, version }` - `environmentClasses: optional array of object { id, bool, description, 7 more }` - `id: optional string` - `bool: optional object { default }` - `default: optional boolean` - `description: optional string` - `display: optional object { default }` - `default: optional string` - `enum: optional object { default, defaultValue, possibleValues, values }` - `default: optional string` deprecated, will be removed, use default_value instead - `defaultValue: optional object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `possibleValues: optional array of object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `values: optional array of string` deprecated, will be removed, use possible_values instead - `int: optional object { default, max, min }` - `default: optional number` - `max: optional number` - `min: optional number` - `name: optional string` - `required: optional boolean` - `secret: optional boolean` - `string: optional object { default, pattern }` - `default: optional string` - `pattern: optional string` - `runnerConfig: optional array of object { id, bool, description, 7 more }` - `id: optional string` - `bool: optional object { default }` - `default: optional boolean` - `description: optional string` - `display: optional object { default }` - `default: optional string` - `enum: optional object { default, defaultValue, possibleValues, values }` - `default: optional string` deprecated, will be removed, use default_value instead - `defaultValue: optional object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `possibleValues: optional array of object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `values: optional array of string` deprecated, will be removed, use possible_values instead - `int: optional object { default, max, min }` - `default: optional number` - `max: optional number` - `min: optional number` - `name: optional string` - `required: optional boolean` - `secret: optional boolean` - `string: optional object { default, pattern }` - `default: optional string` - `pattern: optional string` - `scm: optional array of object { defaultHosts, name, oauth, 2 more }` - `defaultHosts: optional array of string` - `name: optional string` - `oauth: optional object { callbackUrl }` - `callbackUrl: optional string` callback_url is the URL the OAuth app will redirect to after the user has authenticated. - `pat: optional object { description, docsLink }` - `description: optional string` description is a human-readable description of the PAT. - `docsLink: optional string` docs_link is a link to the documentation on how to create a PAT for this SCM system. - `scmId: optional string` - `version: optional string` The schema version ### Schema Retrieve Response - `SchemaRetrieveResponse object { schema }` - `schema: optional RunnerConfigurationSchema` - `environmentClasses: optional array of object { id, bool, description, 7 more }` - `id: optional string` - `bool: optional object { default }` - `default: optional boolean` - `description: optional string` - `display: optional object { default }` - `default: optional string` - `enum: optional object { default, defaultValue, possibleValues, values }` - `default: optional string` deprecated, will be removed, use default_value instead - `defaultValue: optional object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `possibleValues: optional array of object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `values: optional array of string` deprecated, will be removed, use possible_values instead - `int: optional object { default, max, min }` - `default: optional number` - `max: optional number` - `min: optional number` - `name: optional string` - `required: optional boolean` - `secret: optional boolean` - `string: optional object { default, pattern }` - `default: optional string` - `pattern: optional string` - `runnerConfig: optional array of object { id, bool, description, 7 more }` - `id: optional string` - `bool: optional object { default }` - `default: optional boolean` - `description: optional string` - `display: optional object { default }` - `default: optional string` - `enum: optional object { default, defaultValue, possibleValues, values }` - `default: optional string` deprecated, will be removed, use default_value instead - `defaultValue: optional object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `possibleValues: optional array of object { detail, subtitle, title }` - `detail: optional string` - `subtitle: optional string` - `title: optional string` - `values: optional array of string` deprecated, will be removed, use possible_values instead - `int: optional object { default, max, min }` - `default: optional number` - `max: optional number` - `min: optional number` - `name: optional string` - `required: optional boolean` - `secret: optional boolean` - `string: optional object { default, pattern }` - `default: optional string` - `pattern: optional string` - `scm: optional array of object { defaultHosts, name, oauth, 2 more }` - `defaultHosts: optional array of string` - `name: optional string` - `oauth: optional object { callbackUrl }` - `callbackUrl: optional string` callback_url is the URL the OAuth app will redirect to after the user has authenticated. - `pat: optional object { description, docsLink }` - `description: optional string` description is a human-readable description of the PAT. - `docsLink: optional string` docs_link is a link to the documentation on how to create a PAT for this SCM system. - `scmId: optional string` - `version: optional string` The schema version # Scm Integrations ## CreateSCMIntegration **post** `/gitpod.v1.RunnerConfigurationService/CreateSCMIntegration` Creates a new SCM integration for a runner. Use this method to: - Configure source control access - Set up repository integrations - Enable code synchronization ### Examples - Create GitHub integration: Sets up GitHub SCM integration. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" scmId: "github" host: "github.com" oauthClientId: "client_id" oauthPlaintextClientSecret: "client_secret" ``` ### Body Parameters - `host: optional string` - `issuerUrl: optional string` issuer_url can be set to override the authentication provider URL, if it doesn't match the SCM host. - `oauthClientId: optional string` oauth_client_id is the OAuth app's client ID, if OAuth is configured. If configured, oauth_plaintext_client_secret must also be set. - `oauthPlaintextClientSecret: optional string` oauth_plaintext_client_secret is the OAuth app's client secret in clear text. This will first be encrypted with the runner's public key before being stored. - `pat: optional boolean` - `runnerId: optional string` - `scmId: optional string` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtualDirectory: optional string` 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'. ### Returns - `id: optional string` id is a uniquely generated identifier for the SCM integration ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/CreateSCMIntegration \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } ``` ## DeleteSCMIntegration **post** `/gitpod.v1.RunnerConfigurationService/DeleteSCMIntegration` Deletes an SCM integration. Use this method to: - Remove unused integrations - Clean up configurations - Revoke SCM access ### Examples - Delete integration: Removes an SCM integration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/DeleteSCMIntegration \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## ListSCMIntegrations **post** `/gitpod.v1.RunnerConfigurationService/ListSCMIntegrations` Lists SCM integrations for a runner. Use this method to: - View all integrations - Monitor integration status - Check available SCMs ### Examples - List integrations: Shows all SCM integrations. ```yaml filter: runnerIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] pagination: pageSize: 20 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { runnerIds }` - `runnerIds: optional array of string` runner_ids filters the response to only SCM integrations of these Runner IDs - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing scm integrations - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `integrations: optional array of ScmIntegration` - `id: optional string` id is the unique identifier of the SCM integration - `host: optional string` - `oauth: optional ScmIntegrationOAuthConfig` - `clientId: optional string` client_id is the OAuth app's client ID in clear text. - `encryptedClientSecret: optional string` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuerUrl: optional string` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: optional boolean` - `runnerId: optional string` - `scmId: optional string` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtualDirectory: optional string` 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'. - `pagination: optional object { nextToken }` pagination contains the pagination options for listing scm integrations - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/ListSCMIntegrations \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "integrations": [ { "id": "id", "host": "host", "oauth": { "clientId": "clientId", "encryptedClientSecret": "U3RhaW5sZXNzIHJvY2tz", "issuerUrl": "issuerUrl" }, "pat": true, "runnerId": "runnerId", "scmId": "scmId", "virtualDirectory": "virtualDirectory" } ], "pagination": { "nextToken": "nextToken" } } ``` ## GetSCMIntegration **post** `/gitpod.v1.RunnerConfigurationService/GetSCMIntegration` Gets details about a specific SCM integration. Use this method to: - View integration settings - Check integration status - Verify configuration ### Examples - Get integration details: Retrieves information about a specific integration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Returns - `integration: optional ScmIntegration` - `id: optional string` id is the unique identifier of the SCM integration - `host: optional string` - `oauth: optional ScmIntegrationOAuthConfig` - `clientId: optional string` client_id is the OAuth app's client ID in clear text. - `encryptedClientSecret: optional string` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuerUrl: optional string` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: optional boolean` - `runnerId: optional string` - `scmId: optional string` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtualDirectory: optional string` 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'. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/GetSCMIntegration \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "integration": { "id": "id", "host": "host", "oauth": { "clientId": "clientId", "encryptedClientSecret": "U3RhaW5sZXNzIHJvY2tz", "issuerUrl": "issuerUrl" }, "pat": true, "runnerId": "runnerId", "scmId": "scmId", "virtualDirectory": "virtualDirectory" } } ``` ## UpdateSCMIntegration **post** `/gitpod.v1.RunnerConfigurationService/UpdateSCMIntegration` Updates an existing SCM integration. Use this method to: - Modify integration settings - Update credentials - Change configuration ### Examples - Update integration: Updates OAuth credentials. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" oauthClientId: "new_client_id" oauthPlaintextClientSecret: "new_client_secret" ``` ### Body Parameters - `id: optional string` - `issuerUrl: optional string` issuer_url can be set to override the authentication provider URL, if it doesn't match the SCM host. - `oauthClientId: optional string` oauth_client_id can be set to update the OAuth app's client ID. If an empty string is set, the OAuth configuration will be removed (regardless of whether a client secret is set), and any existing Host Authentication Tokens for the SCM integration's runner and host that were created using the OAuth app will be deleted. This might lead to users being unable to access their repositories until they re-authenticate. - `oauthPlaintextClientSecret: optional string` oauth_plaintext_client_secret can be set to update the OAuth app's client secret. The cleartext secret will be encrypted with the runner's public key before being stored. - `pat: optional boolean` pat can be set to enable or disable Personal Access Tokens support. When disabling PATs, any existing Host Authentication Tokens for the SCM integration's runner and host that were created using a PAT will be deleted. This might lead to users being unable to access their repositories until they re-authenticate. - `virtualDirectory: optional string` 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'. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/UpdateSCMIntegration \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## Domain Types ### Scm Integration - `ScmIntegration object { id, host, oauth, 4 more }` - `id: optional string` id is the unique identifier of the SCM integration - `host: optional string` - `oauth: optional ScmIntegrationOAuthConfig` - `clientId: optional string` client_id is the OAuth app's client ID in clear text. - `encryptedClientSecret: optional string` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuerUrl: optional string` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: optional boolean` - `runnerId: optional string` - `scmId: optional string` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtualDirectory: optional string` 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'. ### Scm Integration OAuth Config - `ScmIntegrationOAuthConfig object { clientId, encryptedClientSecret, issuerUrl }` - `clientId: optional string` client_id is the OAuth app's client ID in clear text. - `encryptedClientSecret: optional string` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuerUrl: optional string` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. ### Scm Integration Create Response - `ScmIntegrationCreateResponse object { id }` - `id: optional string` id is a uniquely generated identifier for the SCM integration ### Scm Integration Delete Response - `ScmIntegrationDeleteResponse = unknown` ### Scm Integration Retrieve Response - `ScmIntegrationRetrieveResponse object { integration }` - `integration: optional ScmIntegration` - `id: optional string` id is the unique identifier of the SCM integration - `host: optional string` - `oauth: optional ScmIntegrationOAuthConfig` - `clientId: optional string` client_id is the OAuth app's client ID in clear text. - `encryptedClientSecret: optional string` encrypted_client_secret is the OAuth app's secret encrypted with the runner's public key. - `issuerUrl: optional string` issuer_url is used to override the authentication provider URL, if it doesn't match the SCM host. +optional if not set, this account is owned by the installation. - `pat: optional boolean` - `runnerId: optional string` - `scmId: optional string` scm_id references the scm_id in the runner's configuration schema that this integration is for - `virtualDirectory: optional string` 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'. ### Scm Integration Update Response - `ScmIntegrationUpdateResponse = unknown`