Runners
CheckAuthenticationForHost
CheckRepositoryAccess
CreateRunner
CreateRunnerLogsToken
CreateRunnerToken
DeleteRunner
ListRunners
ListSCMOrganizations
ParseContextURL
GetRunner
SearchRepositories
UpdateRunner
ModelsExpand Collapse
Runner object { createdAt, creator, kind, 7 more }
The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners.
The runner’s specification
The runner’s specification
configuration: optional RunnerConfiguration { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more } The runner’s configuration
The runner’s configuration
auto_update indicates whether the runner should automatically update itself.
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.
metrics contains configuration for the runner’s metrics collection
metrics contains configuration for the runner’s metrics collection
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.
The runner’s status
The runner’s status
gateway_info is information about the gateway to which the runner is connected.
gateway_info is information about the gateway to which the runner is connected.
The runner’s reported message which is shown to users. This message adds more context to the runner’s phase.
public_key is the runner’s public key used for encryption (32 bytes)
RunnerConfiguration object { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more }
auto_update indicates whether the runner should automatically update itself.
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.
metrics contains configuration for the runner’s metrics collection
metrics contains configuration for the runner’s metrics collection
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.
RunnerSpec object { configuration, desiredPhase, variant }
configuration: optional RunnerConfiguration { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more } The runner’s configuration
The runner’s configuration
auto_update indicates whether the runner should automatically update itself.
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.
metrics contains configuration for the runner’s metrics collection
metrics contains configuration for the runner’s metrics collection
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.
RunnerStatus object { additionalInfo, capabilities, gatewayInfo, 10 more } RunnerStatus represents the status of a runner
RunnerStatus represents the status of a runner
gateway_info is information about the gateway to which the runner is connected.
gateway_info is information about the gateway to which the runner is connected.
The runner’s reported message which is shown to users. This message adds more context to the runner’s phase.
public_key is the runner’s public key used for encryption (32 bytes)
RunnerCheckAuthenticationForHostResponse object { authenticated, authenticationUrl, patSupported, 4 more }
scm_name is the human-readable name of the SCM provider (e.g., “GitHub”, “GitLab”)
supportsOauth2: optional object { authUrl, docsUrl } supports_oauth2 indicates that the host supports OAuth2 authentication
supports_oauth2 indicates that the host supports OAuth2 authentication
RunnerCreateResponse object { runner, accessToken, exchangeToken }
The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners.
The runner’s specification
The runner’s specification
configuration: optional RunnerConfiguration { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more } The runner’s configuration
The runner’s configuration
auto_update indicates whether the runner should automatically update itself.
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.
metrics contains configuration for the runner’s metrics collection
metrics contains configuration for the runner’s metrics collection
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.
The runner’s status
The runner’s status
gateway_info is information about the gateway to which the runner is connected.
gateway_info is information about the gateway to which the runner is connected.
The runner’s reported message which is shown to users. This message adds more context to the runner’s phase.
public_key is the runner’s public key used for encryption (32 bytes)
RunnerListScmOrganizationsResponse object { organizations }
organizations: optional array of object { isAdmin, name, url } List of organizations the user belongs to
List of organizations the user belongs to
Whether the user has admin permissions in this organization. Admin permissions typically allow creating organization-level webhooks.
Organization URL (e.g., “https://github.com/gitpod-io”)
RunnerParseContextURLResponse object { git, issue, originalContextUrl, 4 more }
Deprecatedpr: optional object { id, fromBranch, title, toBranch } Deprecated: Use top-level PullRequest message instead
Deprecated: Use top-level PullRequest message instead
project_ids is a list of projects to which the context URL belongs to.
pullRequest: optional object { id, author, draft, 6 more } PullRequest represents pull request metadata from source control systems.
This message is used across workflow triggers, executions, and agent contexts
to maintain consistent PR information throughout the system.
PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system.
Pull request URL (e.g., “https://github.com/owner/repo/pull/123”)
RunnerRetrieveResponse object { runner }
The runner manager id specifies the runner manager for the managed runner. This field is only set for managed runners.
The runner’s specification
The runner’s specification
configuration: optional RunnerConfiguration { autoUpdate, devcontainerImageCacheEnabled, logLevel, 4 more } The runner’s configuration
The runner’s configuration
auto_update indicates whether the runner should automatically update itself.
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.
metrics contains configuration for the runner’s metrics collection
metrics contains configuration for the runner’s metrics collection
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.
The runner’s status
The runner’s status
gateway_info is information about the gateway to which the runner is connected.
gateway_info is information about the gateway to which the runner is connected.
The runner’s reported message which is shown to users. This message adds more context to the runner’s phase.
public_key is the runner’s public key used for encryption (32 bytes)
RunnerSearchRepositoriesResponse object { lastPage, pagination, repositories }
Deprecated: Use pagination token instead. Total pages can be extracted from token.
pagination: optional object { nextToken } Pagination information for the response.
Token format: “NEXT_PAGE/TOTAL_PAGES/TOTAL_COUNT” (e.g., “2/40/1000”).
Use -1 for unknown values (e.g., “2/-1/-1” when totals unavailable).
Empty token means no more pages.
Pagination information for the response. Token format: “NEXT_PAGE/TOTAL_PAGES/TOTAL_COUNT” (e.g., “2/40/1000”). Use -1 for unknown values (e.g., “2/-1/-1” when totals unavailable). Empty token means no more pages.
repositories: optional array of object { name, url } List of repositories matching the search criteria
List of repositories matching the search criteria
Repository URL (e.g., “https://github.com/owner/my-project”)
RunnersConfigurations
ValidateRunnerConfiguration
ModelsExpand Collapse
ConfigurationValidateResponse object { environmentClass, scmIntegration }
environmentClass: optional EnvironmentClassValidationResult { configurationErrors, descriptionError, displayNameError, valid }
RunnersConfigurationsEnvironment Classes
CreateEnvironmentClass
ListEnvironmentClasses
GetEnvironmentClass
UpdateEnvironmentClass
ModelsExpand Collapse
EnvironmentClassRetrieveResponse object { environmentClass }
RunnersConfigurationsHost Authentication Tokens
CreateHostAuthenticationToken
DeleteHostAuthenticationToken
ListHostAuthenticationTokens
GetHostAuthenticationToken
UpdateHostAuthenticationToken
ModelsExpand Collapse
HostAuthenticationToken object { id, expiresAt, host, 6 more }
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.
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 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 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()
method. In Python, a standard datetime.datetime object can be converted
to this format using
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() to obtain a formatter capable of generating timestamps in this format.
HostAuthenticationTokenCreateResponse object { token }
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.
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 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 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()
method. In Python, a standard datetime.datetime object can be converted
to this format using
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() to obtain a formatter capable of generating timestamps in this format.
HostAuthenticationTokenRetrieveResponse object { token }
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.
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 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 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()
method. In Python, a standard datetime.datetime object can be converted
to this format using
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() to obtain a formatter capable of generating timestamps in this format.
RunnersConfigurationsSchema
GetRunnerConfigurationSchema
ModelsExpand Collapse
RunnerConfigurationSchema object { environmentClasses, runnerConfig, scm, version }
environmentClasses: optional array of object { id, bool, description, 7 more }
runnerConfig: optional array of object { id, bool, description, 7 more }
SchemaRetrieveResponse object { schema }
environmentClasses: optional array of object { id, bool, description, 7 more }
runnerConfig: optional array of object { id, bool, description, 7 more }
RunnersConfigurationsScm Integrations
CreateSCMIntegration
DeleteSCMIntegration
ListSCMIntegrations
GetSCMIntegration
UpdateSCMIntegration
ModelsExpand Collapse
ScmIntegration object { id, host, oauth, 4 more }
scm_id references the scm_id in the runner’s configuration schema that this integration is for
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’.
ScmIntegrationRetrieveResponse object { integration }
scm_id references the scm_id in the runner’s configuration schema that this integration is for
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’.