--- title: "UpdateRunnerEnvironmentStatus" method: POST path: "/gitpod.v1.RunnerInteractionService/UpdateRunnerEnvironmentStatus" tags: ["gitpod.v1.RunnerInteractionService"] --- # UpdateRunnerEnvironmentStatus `POST /gitpod.v1.RunnerInteractionService/UpdateRunnerEnvironmentStatus` Provides comprehensive status updates about a managed environment. This method allows runners to report detailed state information about environments they're managing. Use this method to: - Report current environment phase and health status - Update machine and container states - Signal content and devcontainer readiness - Provide access URLs and endpoints - Report warnings or failure conditions ### Examples - Update status: Provides a detailed status update for an environment. ```yaml runnerId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" status: phase: ENVIRONMENT_PHASE_RUNNING statusVersion: "1" failureMessage: [] warningMessage: [] machine: phase: PHASE_RUNNING content: phase: CONTENT_PHASE_READY devcontainer: phase: PHASE_RUNNING environmentUrls: logs: "https://logs.gitpod.io/environment" ports: [] ssh: url: "ssh://ssh.gitpod.io:22" ``` ## Request body - GitpodV1UpdateRunnerEnvironmentStatusRequest - `environmentId` string, uuid — The environment's ID - `runnerId` string, uuid — The runner's identity - `status` GitpodV1EnvironmentStatus — EnvironmentStatus describes an environment status - `activitySignal` GitpodV1EnvironmentActivitySignal — EnvironmentActivitySignal used to signal activity for an environment. - `source` string — source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `timestamp` string, date-time — 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. - `automationsFile` GitpodV1EnvironmentStatusAutomationsFile - `automationsFilePath` string — automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence` 'PRESENCE_UNSPECIFIED' | 'PRESENCE_ABSENT' | 'PRESENCE_DISCOVERED' | 'PRESENCE_SPECIFIED' - `failureMessage` string — failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase` 'CONTENT_PHASE_UNSPECIFIED' | 'CONTENT_PHASE_CREATING' | 'CONTENT_PHASE_INITIALIZING' | 'CONTENT_PHASE_READY' | 'CONTENT_PHASE_UPDATING' | 'CONTENT_PHASE_FAILED' | 'CONTENT_PHASE_UNAVAILABLE' - `session` string — session is the automations file session that is currently applied in the environment. - `warningMessage` string — warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `codex` GitpodV1EnvironmentStatusCodexStatus — CodexStatus describes the direct Codex CLI provisioned in the environment. - `failureMessage` string — failure_message contains the reason Codex provisioning or app-server startup failed. - `phase` 'PHASE_UNSPECIFIED' | 'PHASE_DISABLED' | 'PHASE_PROVISIONING' | 'PHASE_STARTING' | 'PHASE_READY' | 'PHASE_RETRYING' | 'PHASE_FAILED' - `version` string — version is the installed Codex CLI version, when known. - `content` GitpodV1EnvironmentStatusContent - `contentLocationInMachine` string — content_location_in_machine is the location of the content in the machine - `failureMessage` string — failure_message contains the reason the content initialization failed. - `git` GitpodV1EnvironmentGitStatus - `branch` string — branch is branch we're currently on - `changedFiles` GitpodV1FileChange[] — changed_files is an array of changed files in the environment, possibly truncated - `changeType` 'CHANGE_TYPE_UNSPECIFIED' | 'CHANGE_TYPE_ADDED' | 'CHANGE_TYPE_MODIFIED' | 'CHANGE_TYPE_DELETED' | 'CHANGE_TYPE_RENAMED' | 'CHANGE_TYPE_COPIED' | 'CHANGE_TYPE_UPDATED_BUT_UNMERGED' | 'CHANGE_TYPE_UNTRACKED' — ChangeType is the type of change that happened to the file - `oldPath` string — old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `path` string — path is the path of the file - `cloneUrl` string — clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit` string — latest_commit is the most recent commit on the current branch - `totalChangedFiles` integer - `totalUnpushedCommits` integer — the total number of unpushed changes - `unpushedCommits` string[] — unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase` 'CONTENT_PHASE_UNSPECIFIED' | 'CONTENT_PHASE_CREATING' | 'CONTENT_PHASE_INITIALIZING' | 'CONTENT_PHASE_READY' | 'CONTENT_PHASE_UPDATING' | 'CONTENT_PHASE_FAILED' | 'CONTENT_PHASE_UNAVAILABLE' - `session` string — session is the session that is currently active in the environment. - `warningMessage` string — warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer` GitpodV1EnvironmentStatusDevContainer - `containerId` string — container_id is the ID of the container. - `containerName` string — container_name is the name of the container that is used to connect to the devcontainer - `devcontainerFilePath` string — devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence` 'PRESENCE_UNSPECIFIED' | 'PRESENCE_GENERATED' | 'PRESENCE_DISCOVERED' | 'PRESENCE_SPECIFIED' - `devcontainerconfigInSync` boolean — devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `failureMessage` string — failure_message contains the reason the devcontainer failed to operate. - `phase` 'PHASE_UNSPECIFIED' | 'PHASE_CREATING' | 'PHASE_RUNNING' | 'PHASE_STOPPED' | 'PHASE_FAILED' - `remoteUser` string — remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder` string — remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync` boolean — secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session` string — session is the session that is currently active in the devcontainer. - `warningMessage` string — warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls` GitpodV1EnvironmentStatusEnvironmentURLs - `logs` string — logs is the URL at which the environment logs can be accessed. - `ops` string — ops is the URL at which the environment ops service can be accessed. - `ports` GitpodV1EnvironmentStatusEnvironmentPortURL[] - `port` integer — port is the port number of the environment port - `url` string — url is the URL at which the environment port can be accessed - `ssh` GitpodV1EnvironmentStatusEnvironmentSSHURL - `url` string - `supportBundle` string — support_bundle is the URL at which the environment support bundle can be accessed. - `vmLiveUsage` string — vm_live_usage is the URL at which the environment's live VM resource usage can be accessed. - `failureMessage` string[] — failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `machine` GitpodV1EnvironmentStatusMachine - `dualDisk` boolean — dual_disk indicates the environment is running with a dual-disk layout (separate system and data disks). Set by the runner based on actual machine configuration. - `failureMessage` string — failure_message contains the reason the machine failed to operate. - `phase` 'PHASE_UNSPECIFIED' | 'PHASE_CREATING' | 'PHASE_STARTING' | 'PHASE_RUNNING' | 'PHASE_STOPPING' | 'PHASE_STOPPED' | 'PHASE_DELETING' | 'PHASE_DELETED' - `session` string — session is the session that is currently active in the machine. - `timeout` string — timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions` GitpodV1EnvironmentStatusMachineVersions - `amiId` string - `supervisorCommit` string - `supervisorVersion` string - `warningMessage` string — warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase` 'ENVIRONMENT_PHASE_UNSPECIFIED' | 'ENVIRONMENT_PHASE_CREATING' | 'ENVIRONMENT_PHASE_STARTING' | 'ENVIRONMENT_PHASE_RUNNING' | 'ENVIRONMENT_PHASE_UPDATING' | 'ENVIRONMENT_PHASE_STOPPING' | 'ENVIRONMENT_PHASE_STOPPED' | 'ENVIRONMENT_PHASE_DELETING' | 'ENVIRONMENT_PHASE_DELETED' - `runnerAck` GitpodV1EnvironmentStatusRunnerACK — RunnerACK is the acknowledgement from the runner that is has received the environment spec. - `message` string - `specVersion` string - `statusCode` 'STATUS_CODE_UNSPECIFIED' | 'STATUS_CODE_OK' | 'STATUS_CODE_INVALID_RESOURCE' | 'STATUS_CODE_FAILED_PRECONDITION' - `secrets` GitpodV1EnvironmentStatusSecret[] — secrets contains the status of the environment secrets - `failureMessage` string — failure_message contains the reason the secret failed to be materialize. - `id` string — id is the unique identifier of the secret. - `phase` 'CONTENT_PHASE_UNSPECIFIED' | 'CONTENT_PHASE_CREATING' | 'CONTENT_PHASE_INITIALIZING' | 'CONTENT_PHASE_READY' | 'CONTENT_PHASE_UPDATING' | 'CONTENT_PHASE_FAILED' | 'CONTENT_PHASE_UNAVAILABLE' - `secretName` string - `session` string — session is the session that is currently active in the environment. - `warningMessage` string — warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys` GitpodV1EnvironmentStatusSSHPublicKey[] — ssh_public_keys contains the status of the environment ssh public keys - `id` string — id is the unique identifier of the public key - `phase` 'CONTENT_PHASE_UNSPECIFIED' | 'CONTENT_PHASE_CREATING' | 'CONTENT_PHASE_INITIALIZING' | 'CONTENT_PHASE_READY' | 'CONTENT_PHASE_UPDATING' | 'CONTENT_PHASE_FAILED' | 'CONTENT_PHASE_UNAVAILABLE' - `statusVersion` string — version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `warningMessage` string[] — warning_message contains warnings, e.g. when the environment is present but not in the expected state. ## Response `200` Success - GitpodV1UpdateRunnerEnvironmentStatusResponse ## Other responses - `default` — Error --- [API](https://skmtc.net/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.net/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/versions/44d50c2ac284/schema)