# Environments ## CreateEnvironment **post** `/gitpod.v1.EnvironmentService/CreateEnvironment` Creates a development environment from a context URL (e.g. Git repository) and starts it. The `class` field must be a valid environment class ID. You can find a list of available environment classes with the `ListEnvironmentClasses` method. ### Examples - Create from context URL: Creates an environment from a Git repository URL with default settings. ```yaml spec: machine: class: "d2c94c27-3b76-4a42-b88c-95a85e392c68" content: initializer: specs: - contextUrl: url: "https://github.com/gitpod-io/gitpod" ``` - Create from Git repository: Creates an environment from a Git repository with specific branch targeting. ```yaml spec: machine: class: "d2c94c27-3b76-4a42-b88c-95a85e392c68" content: initializer: specs: - git: remoteUri: "https://github.com/gitpod-io/gitpod" cloneTarget: "main" targetMode: "CLONE_TARGET_MODE_REMOTE_BRANCH" ``` - Create with custom timeout and ports: Creates an environment with custom inactivity timeout and exposed port configuration. ```yaml spec: machine: class: "d2c94c27-3b76-4a42-b88c-95a85e392c68" content: initializer: specs: - contextUrl: url: "https://github.com/gitpod-io/gitpod" timeout: disconnected: "7200s" # 2 hours in seconds ports: - port: 3000 admission: "ADMISSION_LEVEL_EVERYONE" name: "Web App" ``` ### Body Parameters - `name: optional string` name is a user-defined identifier for the environment. If not specified, the system will generate a name. - `sessionId: optional string` session_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly. - `spec: optional EnvironmentSpec` spec is the configuration of the environment that's required for the to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. ### Returns - `environment: Environment` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/CreateEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "environment": { "id": "id", "metadata": { "annotations": { "foo": "string" }, "archivedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "lastStartedAt": "2019-12-27T18:11:19.117Z", "lockdownAt": "2019-12-27T18:11:19.117Z", "name": "name", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "originalContextUrl": "originalContextUrl", "prebuildId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "projectId", "role": "ENVIRONMENT_ROLE_UNSPECIFIED", "runnerId": "runnerId", "sessionId": "sessionId" }, "spec": { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "automationsFile": { "automationsFilePath": "automationsFilePath", "session": "session", "triggerFilter": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "content": { "gitEmail": "gitEmail", "gitUsername": "gitUsername", "initializer": { "specs": [ { "contextUrl": { "url": "https://example.com" }, "git": { "checkoutLocation": "checkoutLocation", "cloneTarget": "cloneTarget", "remoteUri": "remoteUri", "targetMode": "CLONE_TARGET_MODE_UNSPECIFIED", "upstreamRemoteUri": "upstreamRemoteUri" } } ] }, "session": "session" }, "desiredPhase": "ENVIRONMENT_PHASE_UNSPECIFIED", "devcontainer": { "defaultDevcontainerImage": "defaultDevcontainerImage", "devcontainerFilePath": "devcontainerFilePath", "dotfiles": { "repository": "https://example.com" }, "lifecycleStage": "LIFECYCLE_STAGE_UNSPECIFIED", "session": "session" }, "kernelControlsConfig": { "bpfDebugLevel": "BPF_DEBUG_LEVEL_UNSPECIFIED", "veto": { "exec": { "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED", "denyBlockDevices": true, "denylist": [ "string" ], "enabled": true, "resolveBareNames": true, "untouchable": true, "watch": true } } }, "machine": { "class": "class", "preferDualDisk": true, "session": "session" }, "ports": [ { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "authNonce": "authNonce", "name": "x", "port": 1024, "protocol": "PROTOCOL_UNSPECIFIED" } ], "secrets": [ { "id": "id", "apiOnly": true, "containerRegistryBasicAuthHost": "containerRegistryBasicAuthHost", "credentialProxy": { "format": "FORMAT_UNSPECIFIED", "header": "header", "targetHosts": [ "string" ] }, "environmentVariable": "environmentVariable", "filePath": "filePath", "gitCredentialHost": "gitCredentialHost", "name": "name", "scope": "SCOPE_UNSPECIFIED", "session": "session", "source": "source", "sourceRef": "sourceRef" } ], "specVersion": "specVersion", "sshPublicKeys": [ { "id": "id", "value": "value" } ], "timeout": { "disconnected": "+9125115.360s" }, "workflowActionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "status": { "activitySignal": { "source": "xxx", "timestamp": "2019-12-27T18:11:19.117Z" }, "automationsFile": { "automationsFilePath": "automationsFilePath", "automationsFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "content": { "contentLocationInMachine": "contentLocationInMachine", "failureMessage": "failureMessage", "git": { "branch": "branch", "changedFiles": [ { "changeType": "CHANGE_TYPE_UNSPECIFIED", "oldPath": "oldPath", "path": "path" } ], "cloneUrl": "cloneUrl", "latestCommit": "latestCommit", "totalChangedFiles": 0, "totalUnpushedCommits": 0, "unpushedCommits": [ "string" ] }, "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "devcontainer": { "containerId": "containerId", "containerName": "containerName", "devcontainerconfigInSync": true, "devcontainerFilePath": "devcontainerFilePath", "devcontainerFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "remoteUser": "remoteUser", "remoteWorkspaceFolder": "remoteWorkspaceFolder", "secretsInSync": true, "session": "session", "warningMessage": "warningMessage" }, "environmentUrls": { "logs": "logs", "ops": "ops", "ports": [ { "port": 1024, "url": "url" } ], "ssh": { "url": "url" }, "supportBundle": "supportBundle", "vmLiveUsage": "vmLiveUsage" }, "failureMessage": [ "string" ], "machine": { "dualDisk": true, "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "session": "session", "timeout": "timeout", "versions": { "amiId": "amiId", "supervisorCommit": "supervisorCommit", "supervisorVersion": "supervisorVersion" }, "warningMessage": "warningMessage" }, "phase": "ENVIRONMENT_PHASE_UNSPECIFIED", "runnerAck": { "message": "message", "specVersion": "specVersion", "statusCode": "STATUS_CODE_UNSPECIFIED" }, "secrets": [ { "id": "id", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "secretName": "secretName", "session": "session", "warningMessage": "warningMessage" } ], "sshPublicKeys": [ { "id": "id", "phase": "CONTENT_PHASE_UNSPECIFIED" } ], "statusVersion": "statusVersion", "warningMessage": [ "string" ] } } } ``` ## CreateEnvironmentAccessToken **post** `/gitpod.v1.EnvironmentService/CreateEnvironmentAccessToken` Creates an access token for the environment. Generated tokens are valid for one hour and provide environment-specific access permissions. The token is scoped to a specific environment. ### Examples - Generate environment token: Creates a temporary access token for accessing an environment. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `environmentId: string` environment_id specifies the environment for which the access token should be created. ### Returns - `accessToken: string` access_token is the token that can be used for environment authentication ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/CreateEnvironmentAccessToken \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "environmentId": "07e03a28-65a5-4d98-b532-8ea67b188048" }' ``` #### Response ```json { "accessToken": "accessToken" } ``` ## CreateEnvironmentFromProject **post** `/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject` Creates an environment from an existing project configuration and starts it. This method uses project settings as defaults but allows overriding specific configurations. Project settings take precedence over default configurations, while custom specifications in the request override project settings. ### Examples - Create with project defaults: Creates an environment using all default settings from the project configuration. ```yaml projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" ``` - Create with custom compute resources: Creates an environment from project with custom machine class and timeout settings. ```yaml projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" spec: machine: class: "d2c94c27-3b76-4a42-b88c-95a85e392c68" timeout: disconnected: "14400s" # 4 hours in seconds ``` ### Body Parameters - `name: optional string` name is a user-defined identifier for the environment. If not specified, the system will generate a name. - `projectId: optional string` - `sessionId: optional string` session_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment Configuration already defined in the Project will override parts of the spec, if set - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. ### Returns - `environment: Environment` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "environment": { "id": "id", "metadata": { "annotations": { "foo": "string" }, "archivedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "lastStartedAt": "2019-12-27T18:11:19.117Z", "lockdownAt": "2019-12-27T18:11:19.117Z", "name": "name", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "originalContextUrl": "originalContextUrl", "prebuildId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "projectId", "role": "ENVIRONMENT_ROLE_UNSPECIFIED", "runnerId": "runnerId", "sessionId": "sessionId" }, "spec": { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "automationsFile": { "automationsFilePath": "automationsFilePath", "session": "session", "triggerFilter": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "content": { "gitEmail": "gitEmail", "gitUsername": "gitUsername", "initializer": { "specs": [ { "contextUrl": { "url": "https://example.com" }, "git": { "checkoutLocation": "checkoutLocation", "cloneTarget": "cloneTarget", "remoteUri": "remoteUri", "targetMode": "CLONE_TARGET_MODE_UNSPECIFIED", "upstreamRemoteUri": "upstreamRemoteUri" } } ] }, "session": "session" }, "desiredPhase": "ENVIRONMENT_PHASE_UNSPECIFIED", "devcontainer": { "defaultDevcontainerImage": "defaultDevcontainerImage", "devcontainerFilePath": "devcontainerFilePath", "dotfiles": { "repository": "https://example.com" }, "lifecycleStage": "LIFECYCLE_STAGE_UNSPECIFIED", "session": "session" }, "kernelControlsConfig": { "bpfDebugLevel": "BPF_DEBUG_LEVEL_UNSPECIFIED", "veto": { "exec": { "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED", "denyBlockDevices": true, "denylist": [ "string" ], "enabled": true, "resolveBareNames": true, "untouchable": true, "watch": true } } }, "machine": { "class": "class", "preferDualDisk": true, "session": "session" }, "ports": [ { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "authNonce": "authNonce", "name": "x", "port": 1024, "protocol": "PROTOCOL_UNSPECIFIED" } ], "secrets": [ { "id": "id", "apiOnly": true, "containerRegistryBasicAuthHost": "containerRegistryBasicAuthHost", "credentialProxy": { "format": "FORMAT_UNSPECIFIED", "header": "header", "targetHosts": [ "string" ] }, "environmentVariable": "environmentVariable", "filePath": "filePath", "gitCredentialHost": "gitCredentialHost", "name": "name", "scope": "SCOPE_UNSPECIFIED", "session": "session", "source": "source", "sourceRef": "sourceRef" } ], "specVersion": "specVersion", "sshPublicKeys": [ { "id": "id", "value": "value" } ], "timeout": { "disconnected": "+9125115.360s" }, "workflowActionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "status": { "activitySignal": { "source": "xxx", "timestamp": "2019-12-27T18:11:19.117Z" }, "automationsFile": { "automationsFilePath": "automationsFilePath", "automationsFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "content": { "contentLocationInMachine": "contentLocationInMachine", "failureMessage": "failureMessage", "git": { "branch": "branch", "changedFiles": [ { "changeType": "CHANGE_TYPE_UNSPECIFIED", "oldPath": "oldPath", "path": "path" } ], "cloneUrl": "cloneUrl", "latestCommit": "latestCommit", "totalChangedFiles": 0, "totalUnpushedCommits": 0, "unpushedCommits": [ "string" ] }, "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "devcontainer": { "containerId": "containerId", "containerName": "containerName", "devcontainerconfigInSync": true, "devcontainerFilePath": "devcontainerFilePath", "devcontainerFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "remoteUser": "remoteUser", "remoteWorkspaceFolder": "remoteWorkspaceFolder", "secretsInSync": true, "session": "session", "warningMessage": "warningMessage" }, "environmentUrls": { "logs": "logs", "ops": "ops", "ports": [ { "port": 1024, "url": "url" } ], "ssh": { "url": "url" }, "supportBundle": "supportBundle", "vmLiveUsage": "vmLiveUsage" }, "failureMessage": [ "string" ], "machine": { "dualDisk": true, "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "session": "session", "timeout": "timeout", "versions": { "amiId": "amiId", "supervisorCommit": "supervisorCommit", "supervisorVersion": "supervisorVersion" }, "warningMessage": "warningMessage" }, "phase": "ENVIRONMENT_PHASE_UNSPECIFIED", "runnerAck": { "message": "message", "specVersion": "specVersion", "statusCode": "STATUS_CODE_UNSPECIFIED" }, "secrets": [ { "id": "id", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "secretName": "secretName", "session": "session", "warningMessage": "warningMessage" } ], "sshPublicKeys": [ { "id": "id", "phase": "CONTENT_PHASE_UNSPECIFIED" } ], "statusVersion": "statusVersion", "warningMessage": [ "string" ] } } } ``` ## CreateEnvironmentLogsToken **post** `/gitpod.v1.EnvironmentService/CreateEnvironmentLogsToken` Creates an access token for retrieving environment logs. Generated tokens are valid for one hour and provide read-only access to the environment's logs. ### Examples - Generate logs token: Creates a temporary access token for retrieving environment logs. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `environmentId: optional string` environment_id specifies the environment for which the logs token should be created. +required ### Returns - `accessToken: string` access_token is the token that can be used to access the logs of the environment ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/CreateEnvironmentLogsToken \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "accessToken": "accessToken" } ``` ## DeleteEnvironment **post** `/gitpod.v1.EnvironmentService/DeleteEnvironment` Permanently deletes an environment. Running environments are automatically stopped before deletion. If force is true, the environment is deleted immediately without graceful shutdown. ### Examples - Delete with graceful shutdown: Deletes an environment after gracefully stopping it. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" force: false ``` - Force delete: Immediately deletes an environment without waiting for graceful shutdown. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" force: true ``` ### Body Parameters - `environmentId: optional string` environment_id specifies the environment that is going to delete. +required - `force: optional boolean` force indicates whether the environment should be deleted forcefully When force deleting an Environment, the Environment is removed immediately and environment lifecycle is not respected. Force deleting can result in data loss on the environment. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/DeleteEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## ListEnvironments **post** `/gitpod.v1.EnvironmentService/ListEnvironments` Lists all environments matching the specified criteria. Use this method to find and monitor environments across your organization. Results are ordered by creation time with newest environments first. ### Examples - List running environments for a project: Retrieves all running environments for a specific project with pagination. ```yaml filter: statusPhases: ["ENVIRONMENT_PHASE_RUNNING"] projectIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] pagination: pageSize: 10 ``` - List all environments for a specific runner: Filters environments by runner ID and creator ID. ```yaml filter: runnerIds: ["e6aa9c54-89d3-42c1-ac31-bd8d8f1concentrate"] creatorIds: ["f53d2330-3795-4c5d-a1f3-453121af9c60"] ``` - List stopped and deleted environments: Retrieves all environments in stopped or deleted state. ```yaml filter: statusPhases: ["ENVIRONMENT_PHASE_STOPPED", "ENVIRONMENT_PHASE_DELETED"] ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { archivalStatus, createdBefore, creatorIds, 6 more }` - `archivalStatus: optional "ARCHIVAL_STATUS_UNSPECIFIED" or "ARCHIVAL_STATUS_ACTIVE" or "ARCHIVAL_STATUS_ARCHIVED" or "ARCHIVAL_STATUS_ALL"` archival_status filters the response based on environment archive status - `"ARCHIVAL_STATUS_UNSPECIFIED"` - `"ARCHIVAL_STATUS_ACTIVE"` - `"ARCHIVAL_STATUS_ARCHIVED"` - `"ARCHIVAL_STATUS_ALL"` - `createdBefore: optional string` created_before filters environments created before this timestamp - `creatorIds: optional array of string` creator_ids filters the response to only Environments created by specified members - `projectIds: optional array of string` project_ids filters the response to only Environments associated with the specified projects - `roles: optional array of EnvironmentRole` roles filters the response to only Environments with the specified roles - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerIds: optional array of string` runner_ids filters the response to only Environments running on these Runner IDs - `runnerKinds: optional array of RunnerKind` runner_kinds filters the response to only Environments running on these Runner Kinds - `"RUNNER_KIND_UNSPECIFIED"` - `"RUNNER_KIND_LOCAL"` - `"RUNNER_KIND_REMOTE"` - `"RUNNER_KIND_LOCAL_CONFIGURATION"` - `sessionIds: optional array of string` session_ids filters the response to only environments belonging to the specified sessions - `statusPhases: optional array of EnvironmentPhase` actual_phases is a list of phases the environment must be in for it to be returned in the API call - `"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"` - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing environments - `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 - `environments: optional array of Environment` environments are the environments that matched the query - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. - `pagination: optional object { nextToken }` pagination contains the pagination options for listing environments - `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.EnvironmentService/ListEnvironments \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "count": { "relation": "COUNT_RESPONSE_RELATION_UNSPECIFIED", "value": 0 }, "environments": [ { "id": "id", "metadata": { "annotations": { "foo": "string" }, "archivedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "lastStartedAt": "2019-12-27T18:11:19.117Z", "lockdownAt": "2019-12-27T18:11:19.117Z", "name": "name", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "originalContextUrl": "originalContextUrl", "prebuildId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "projectId", "role": "ENVIRONMENT_ROLE_UNSPECIFIED", "runnerId": "runnerId", "sessionId": "sessionId" }, "spec": { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "automationsFile": { "automationsFilePath": "automationsFilePath", "session": "session", "triggerFilter": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "content": { "gitEmail": "gitEmail", "gitUsername": "gitUsername", "initializer": { "specs": [ { "contextUrl": { "url": "https://example.com" }, "git": { "checkoutLocation": "checkoutLocation", "cloneTarget": "cloneTarget", "remoteUri": "remoteUri", "targetMode": "CLONE_TARGET_MODE_UNSPECIFIED", "upstreamRemoteUri": "upstreamRemoteUri" } } ] }, "session": "session" }, "desiredPhase": "ENVIRONMENT_PHASE_UNSPECIFIED", "devcontainer": { "defaultDevcontainerImage": "defaultDevcontainerImage", "devcontainerFilePath": "devcontainerFilePath", "dotfiles": { "repository": "https://example.com" }, "lifecycleStage": "LIFECYCLE_STAGE_UNSPECIFIED", "session": "session" }, "kernelControlsConfig": { "bpfDebugLevel": "BPF_DEBUG_LEVEL_UNSPECIFIED", "veto": { "exec": { "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED", "denyBlockDevices": true, "denylist": [ "string" ], "enabled": true, "resolveBareNames": true, "untouchable": true, "watch": true } } }, "machine": { "class": "class", "preferDualDisk": true, "session": "session" }, "ports": [ { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "authNonce": "authNonce", "name": "x", "port": 1024, "protocol": "PROTOCOL_UNSPECIFIED" } ], "secrets": [ { "id": "id", "apiOnly": true, "containerRegistryBasicAuthHost": "containerRegistryBasicAuthHost", "credentialProxy": { "format": "FORMAT_UNSPECIFIED", "header": "header", "targetHosts": [ "string" ] }, "environmentVariable": "environmentVariable", "filePath": "filePath", "gitCredentialHost": "gitCredentialHost", "name": "name", "scope": "SCOPE_UNSPECIFIED", "session": "session", "source": "source", "sourceRef": "sourceRef" } ], "specVersion": "specVersion", "sshPublicKeys": [ { "id": "id", "value": "value" } ], "timeout": { "disconnected": "+9125115.360s" }, "workflowActionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "status": { "activitySignal": { "source": "xxx", "timestamp": "2019-12-27T18:11:19.117Z" }, "automationsFile": { "automationsFilePath": "automationsFilePath", "automationsFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "content": { "contentLocationInMachine": "contentLocationInMachine", "failureMessage": "failureMessage", "git": { "branch": "branch", "changedFiles": [ { "changeType": "CHANGE_TYPE_UNSPECIFIED", "oldPath": "oldPath", "path": "path" } ], "cloneUrl": "cloneUrl", "latestCommit": "latestCommit", "totalChangedFiles": 0, "totalUnpushedCommits": 0, "unpushedCommits": [ "string" ] }, "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "devcontainer": { "containerId": "containerId", "containerName": "containerName", "devcontainerconfigInSync": true, "devcontainerFilePath": "devcontainerFilePath", "devcontainerFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "remoteUser": "remoteUser", "remoteWorkspaceFolder": "remoteWorkspaceFolder", "secretsInSync": true, "session": "session", "warningMessage": "warningMessage" }, "environmentUrls": { "logs": "logs", "ops": "ops", "ports": [ { "port": 1024, "url": "url" } ], "ssh": { "url": "url" }, "supportBundle": "supportBundle", "vmLiveUsage": "vmLiveUsage" }, "failureMessage": [ "string" ], "machine": { "dualDisk": true, "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "session": "session", "timeout": "timeout", "versions": { "amiId": "amiId", "supervisorCommit": "supervisorCommit", "supervisorVersion": "supervisorVersion" }, "warningMessage": "warningMessage" }, "phase": "ENVIRONMENT_PHASE_UNSPECIFIED", "runnerAck": { "message": "message", "specVersion": "specVersion", "statusCode": "STATUS_CODE_UNSPECIFIED" }, "secrets": [ { "id": "id", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "secretName": "secretName", "session": "session", "warningMessage": "warningMessage" } ], "sshPublicKeys": [ { "id": "id", "phase": "CONTENT_PHASE_UNSPECIFIED" } ], "statusVersion": "statusVersion", "warningMessage": [ "string" ] } } ], "pagination": { "nextToken": "nextToken" } } ``` ## MarkEnvironmentActive **post** `/gitpod.v1.EnvironmentService/MarkEnvironmentActive` Records environment activity to prevent automatic shutdown. Activity signals should be sent every 5 minutes while the environment is actively being used. The source must be between 3-80 characters. ### Examples - Signal VS Code activity: Records VS Code editor activity to prevent environment shutdown. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" activitySignal: source: "VS Code" timestamp: "2025-02-12T14:30:00Z" ``` ### Body Parameters - `activitySignal: optional EnvironmentActivitySignal` activity_signal specifies the activity. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `environmentId: optional string` The ID of the environment to update activity for. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/MarkEnvironmentActive \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## GetEnvironment **post** `/gitpod.v1.EnvironmentService/GetEnvironment` Gets details about a specific environment including its status, configuration, and context URL. Use this method to: - Check if an environment is ready to use - Get connection details for IDE and exposed ports - Monitor environment health and resource usage - Debug environment setup issues ### Examples - Get environment details: Retrieves detailed information about a specific environment using its unique identifier. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `environmentId: string` environment_id specifies the environment to get ### Returns - `environment: Environment` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/GetEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "environmentId": "07e03a28-65a5-4d98-b532-8ea67b188048" }' ``` #### Response ```json { "environment": { "id": "id", "metadata": { "annotations": { "foo": "string" }, "archivedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "lastStartedAt": "2019-12-27T18:11:19.117Z", "lockdownAt": "2019-12-27T18:11:19.117Z", "name": "name", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "originalContextUrl": "originalContextUrl", "prebuildId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "projectId", "role": "ENVIRONMENT_ROLE_UNSPECIFIED", "runnerId": "runnerId", "sessionId": "sessionId" }, "spec": { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "automationsFile": { "automationsFilePath": "automationsFilePath", "session": "session", "triggerFilter": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "content": { "gitEmail": "gitEmail", "gitUsername": "gitUsername", "initializer": { "specs": [ { "contextUrl": { "url": "https://example.com" }, "git": { "checkoutLocation": "checkoutLocation", "cloneTarget": "cloneTarget", "remoteUri": "remoteUri", "targetMode": "CLONE_TARGET_MODE_UNSPECIFIED", "upstreamRemoteUri": "upstreamRemoteUri" } } ] }, "session": "session" }, "desiredPhase": "ENVIRONMENT_PHASE_UNSPECIFIED", "devcontainer": { "defaultDevcontainerImage": "defaultDevcontainerImage", "devcontainerFilePath": "devcontainerFilePath", "dotfiles": { "repository": "https://example.com" }, "lifecycleStage": "LIFECYCLE_STAGE_UNSPECIFIED", "session": "session" }, "kernelControlsConfig": { "bpfDebugLevel": "BPF_DEBUG_LEVEL_UNSPECIFIED", "veto": { "exec": { "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED", "denyBlockDevices": true, "denylist": [ "string" ], "enabled": true, "resolveBareNames": true, "untouchable": true, "watch": true } } }, "machine": { "class": "class", "preferDualDisk": true, "session": "session" }, "ports": [ { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "authNonce": "authNonce", "name": "x", "port": 1024, "protocol": "PROTOCOL_UNSPECIFIED" } ], "secrets": [ { "id": "id", "apiOnly": true, "containerRegistryBasicAuthHost": "containerRegistryBasicAuthHost", "credentialProxy": { "format": "FORMAT_UNSPECIFIED", "header": "header", "targetHosts": [ "string" ] }, "environmentVariable": "environmentVariable", "filePath": "filePath", "gitCredentialHost": "gitCredentialHost", "name": "name", "scope": "SCOPE_UNSPECIFIED", "session": "session", "source": "source", "sourceRef": "sourceRef" } ], "specVersion": "specVersion", "sshPublicKeys": [ { "id": "id", "value": "value" } ], "timeout": { "disconnected": "+9125115.360s" }, "workflowActionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "status": { "activitySignal": { "source": "xxx", "timestamp": "2019-12-27T18:11:19.117Z" }, "automationsFile": { "automationsFilePath": "automationsFilePath", "automationsFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "content": { "contentLocationInMachine": "contentLocationInMachine", "failureMessage": "failureMessage", "git": { "branch": "branch", "changedFiles": [ { "changeType": "CHANGE_TYPE_UNSPECIFIED", "oldPath": "oldPath", "path": "path" } ], "cloneUrl": "cloneUrl", "latestCommit": "latestCommit", "totalChangedFiles": 0, "totalUnpushedCommits": 0, "unpushedCommits": [ "string" ] }, "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "devcontainer": { "containerId": "containerId", "containerName": "containerName", "devcontainerconfigInSync": true, "devcontainerFilePath": "devcontainerFilePath", "devcontainerFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "remoteUser": "remoteUser", "remoteWorkspaceFolder": "remoteWorkspaceFolder", "secretsInSync": true, "session": "session", "warningMessage": "warningMessage" }, "environmentUrls": { "logs": "logs", "ops": "ops", "ports": [ { "port": 1024, "url": "url" } ], "ssh": { "url": "url" }, "supportBundle": "supportBundle", "vmLiveUsage": "vmLiveUsage" }, "failureMessage": [ "string" ], "machine": { "dualDisk": true, "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "session": "session", "timeout": "timeout", "versions": { "amiId": "amiId", "supervisorCommit": "supervisorCommit", "supervisorVersion": "supervisorVersion" }, "warningMessage": "warningMessage" }, "phase": "ENVIRONMENT_PHASE_UNSPECIFIED", "runnerAck": { "message": "message", "specVersion": "specVersion", "statusCode": "STATUS_CODE_UNSPECIFIED" }, "secrets": [ { "id": "id", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "secretName": "secretName", "session": "session", "warningMessage": "warningMessage" } ], "sshPublicKeys": [ { "id": "id", "phase": "CONTENT_PHASE_UNSPECIFIED" } ], "statusVersion": "statusVersion", "warningMessage": [ "string" ] } } } ``` ## StartEnvironment **post** `/gitpod.v1.EnvironmentService/StartEnvironment` Starts a stopped environment. Use this method to resume work on a previously stopped environment. The environment retains its configuration and workspace content from when it was stopped. ### Examples - Start an environment: Resumes a previously stopped environment with its existing configuration. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `environmentId: optional string` environment_id specifies which environment should be started. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/StartEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## StopEnvironment **post** `/gitpod.v1.EnvironmentService/StopEnvironment` Stops a running environment. Use this method to pause work while preserving the environment's state. The environment can be resumed later using StartEnvironment. ### Examples - Stop an environment: Gracefully stops a running environment while preserving its state. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `environmentId: optional string` environment_id specifies which environment should be stopped. +required ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/StopEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## UnarchiveEnvironment **post** `/gitpod.v1.EnvironmentService/UnarchiveEnvironment` Unarchives an environment. ### Examples - Unarchive an environment: ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Body Parameters - `environmentId: optional string` environment_id specifies the environment to unarchive. +required ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/UnarchiveEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## UpdateEnvironment **post** `/gitpod.v1.EnvironmentService/UpdateEnvironment` Updates an environment's configuration while it is running. Updates are limited to: - Git credentials (username, email) - SSH public keys - Content initialization - Port configurations - Automation files - Environment timeouts ### Examples - Update Git credentials: Updates the Git configuration for the environment. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" spec: content: gitUsername: "example-user" gitEmail: "user@example.com" ``` - Add SSH public key: Adds a new SSH public key for authentication. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" spec: sshPublicKeys: - id: "0194b7c1-c954-718d-91a4-9a742aa5fc11" value: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..." ``` - Update content session: Updates the content session identifier for the environment. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" spec: content: session: "0194b7c1-c954-718d-91a4-9a742aa5fc11" ``` Note: Machine class changes require stopping the environment and creating a new one. ### Body Parameters - `environmentId: optional string` environment_id specifies which environment should be updated. +required - `metadata: optional object { name }` - `name: optional string` name is the user-defined display name of the environment - `spec: optional object { automationsFile, content, devcontainer, 4 more }` - `automationsFile: optional object { automationsFilePath, session }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `content: optional object { gitEmail, gitUsername, initializer, session }` - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` session should be changed to trigger a content reinitialization - `devcontainer: optional object { devcontainerFilePath, session }` - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` session should be changed to trigger a devcontainer rebuild - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `ports: optional array of object { admission, name, port, protocol }` ports controls port sharing - `admission: optional AdmissionLevel` policy of this port - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys to update empty array means nothing to update - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format if not provided, the public key will be removed - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/UpdateEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## Domain Types ### Admission Level - `AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED" or "ADMISSION_LEVEL_OWNER_ONLY" or "ADMISSION_LEVEL_EVERYONE" or 2 more` Admission level describes who can access an environment instance and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` ### Bpf Debug Level - `BpfDebugLevel = "BPF_DEBUG_LEVEL_UNSPECIFIED" or "BPF_DEBUG_LEVEL_INFO" or "BPF_DEBUG_LEVEL_VERBOSE"` BPFDebugLevel controls the verbosity of BPF trace_pipe output (bpf_printk). Applies to all BPF-based agents (veto exec, future agents). - `"BPF_DEBUG_LEVEL_UNSPECIFIED"` - `"BPF_DEBUG_LEVEL_INFO"` - `"BPF_DEBUG_LEVEL_VERBOSE"` ### Environment - `Environment object { id, metadata, spec, status }` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Environment Activity Signal - `EnvironmentActivitySignal object { source, timestamp }` EnvironmentActivitySignal used to signal activity for an environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. ### Environment Metadata - `EnvironmentMetadata object { annotations, archivedAt, createdAt, 10 more }` EnvironmentMetadata is data associated with an environment that's required for other parts of the system to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. ### Environment Phase - `EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED" or "ENVIRONMENT_PHASE_CREATING" or "ENVIRONMENT_PHASE_STARTING" or 6 more` - `"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"` ### Environment Role - `EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED" or "ENVIRONMENT_ROLE_DEFAULT" or "ENVIRONMENT_ROLE_PREBUILD" or "ENVIRONMENT_ROLE_WORKFLOW"` EnvironmentRole represents the role of an environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` ### Environment Spec - `EnvironmentSpec object { admission, automationsFile, content, 10 more }` EnvironmentSpec specifies the configuration of an environment for an environment start - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. ### Environment Status - `EnvironmentStatus object { activitySignal, automationsFile, content, 10 more }` EnvironmentStatus describes an environment status - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `"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: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Kernel Controls Config - `KernelControlsConfig object { veto }` KernelControlsConfig configures kernel-level controls for the environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active ### Veto - `Veto object { exec }` Veto controls kernel-level blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active ### Environment Create Response - `EnvironmentCreateResponse object { environment }` - `environment: Environment` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Environment Create Environment Token Response - `EnvironmentCreateEnvironmentTokenResponse object { accessToken }` - `accessToken: string` access_token is the token that can be used for environment authentication ### Environment Create From Project Response - `EnvironmentCreateFromProjectResponse object { environment }` - `environment: Environment` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Environment Create Logs Token Response - `EnvironmentCreateLogsTokenResponse object { accessToken }` - `accessToken: string` access_token is the token that can be used to access the logs of the environment ### Environment Delete Response - `EnvironmentDeleteResponse = unknown` ### Environment Mark Active Response - `EnvironmentMarkActiveResponse = unknown` ### Environment Retrieve Response - `EnvironmentRetrieveResponse object { environment }` - `environment: Environment` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `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"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"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"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional 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: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"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"` - `oldPath: optional 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: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of 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: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional 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: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Environment Start Response - `EnvironmentStartResponse = unknown` ### Environment Stop Response - `EnvironmentStopResponse = unknown` ### Environment Unarchive Response - `EnvironmentUnarchiveResponse = unknown` ### Environment Update Response - `EnvironmentUpdateResponse = unknown` # Automations ## UpsertAutomationsFile **post** `/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile` Upserts the automations file for the given environment. Use this method to: - Configure environment automations - Update automation settings - Manage automation files ### Examples - Update automations file: Updates or creates the automations configuration. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" automationsFile: services: web-server: name: "Web Server" description: "Development web server" commands: start: "npm run dev" ready: "curl -s http://localhost:3000" triggeredBy: - postDevcontainerStart tasks: build: name: "Build Project" description: "Builds the project artifacts" command: "npm run build" triggeredBy: - postEnvironmentStart ``` ### Body Parameters - `automationsFile: optional AutomationsFile` WARN: Do not remove any field here, as it will break reading automation yaml files. We error if there are any unknown fields in the yaml (to ensure the yaml is correct), but would break if we removed any fields. This includes marking a field as "reserved" in the proto file, this will also break reading the yaml. - `services: optional map[object { commands, description, name, 3 more } ]` - `commands: optional object { ready, start, stop }` - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `description: optional string` - `name: optional string` - `role: optional "" or "default" or "editor" or "ai-agent"` - `""` - `"default"` - `"editor"` - `"ai-agent"` - `runsOn: optional RunsOn` - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `triggeredBy: optional array of "manual" or "postEnvironmentStart" or "postDevcontainerStart" or "prebuild"` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` - `tasks: optional map[object { command, dependsOn, description, 3 more } ]` - `command: optional string` - `dependsOn: optional array of string` - `description: optional string` - `name: optional string` - `runsOn: optional RunsOn` - `triggeredBy: optional array of "manual" or "postEnvironmentStart" or "postDevcontainerStart" or "prebuild"` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` - `environmentId: optional string` ### Returns - `updatedServiceIds: optional array of string` - `updatedTaskIds: optional array of string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "updatedServiceIds": [ "string" ], "updatedTaskIds": [ "string" ] } ``` ## Domain Types ### Automations File - `AutomationsFile object { services, tasks }` WARN: Do not remove any field here, as it will break reading automation yaml files. We error if there are any unknown fields in the yaml (to ensure the yaml is correct), but would break if we removed any fields. This includes marking a field as "reserved" in the proto file, this will also break reading the yaml. - `services: optional map[object { commands, description, name, 3 more } ]` - `commands: optional object { ready, start, stop }` - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `description: optional string` - `name: optional string` - `role: optional "" or "default" or "editor" or "ai-agent"` - `""` - `"default"` - `"editor"` - `"ai-agent"` - `runsOn: optional RunsOn` - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `triggeredBy: optional array of "manual" or "postEnvironmentStart" or "postDevcontainerStart" or "prebuild"` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` - `tasks: optional map[object { command, dependsOn, description, 3 more } ]` - `command: optional string` - `dependsOn: optional array of string` - `description: optional string` - `name: optional string` - `runsOn: optional RunsOn` - `triggeredBy: optional array of "manual" or "postEnvironmentStart" or "postDevcontainerStart" or "prebuild"` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` ### Automation Upsert Response - `AutomationUpsertResponse object { updatedServiceIds, updatedTaskIds }` - `updatedServiceIds: optional array of string` - `updatedTaskIds: optional array of string` # Services ## CreateService **post** `/gitpod.v1.EnvironmentAutomationService/CreateService` Creates a new automation service for an environment. Use this method to: - Set up long-running services - Configure service triggers - Define service dependencies - Specify runtime environments ### Examples - Create basic service: Creates a simple service with start command. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "web-server" name: "Web Server" description: "Runs the development web server" triggeredBy: - postDevcontainerStart: true spec: commands: start: "npm run dev" ready: "curl -s http://localhost:3000" ``` - Create Docker-based service: Creates a service running in a specific container. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "redis" name: "Redis Server" description: "Redis cache service" spec: commands: start: "redis-server" runsOn: docker: image: "redis:7" ``` ### Body Parameters - `environmentId: optional string` - `metadata: optional ServiceMetadata` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional ServiceSpec` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. ### Returns - `service: Service` - `id: string` - `environmentId: optional string` - `metadata: optional ServiceMetadata` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional ServiceSpec` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `status: optional ServiceStatus` - `failureMessage: optional string` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url contains the URL at which the service logs can be accessed. - `output: optional map[string]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: optional ServicePhase` phase is the current phase of the service. - `session: optional string` session is the current session of the service. - `statusVersion: optional string` version of the status update. Service 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. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/CreateService \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "service": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "description": "description", "name": "x", "reference": "reference", "role": "SERVICE_ROLE_UNSPECIFIED", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "commands": { "ready": "ready", "start": "x", "stop": "stop" }, "desiredPhase": "SERVICE_PHASE_UNSPECIFIED", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} }, "session": "session", "specVersion": "specVersion" }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "output": { "foo": "string" }, "phase": "SERVICE_PHASE_UNSPECIFIED", "session": "session", "statusVersion": "statusVersion" } } } ``` ## DeleteService **post** `/gitpod.v1.EnvironmentAutomationService/DeleteService` Deletes an automation service. This call does not block until the service is deleted. If the service is not stopped it will be stopped before deletion. Use this method to: - Remove unused services - Clean up service configurations - Stop and delete services ### Examples - Delete service: Removes a service after stopping it. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" force: false ``` - Force delete: Immediately removes a service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" force: true ``` ### Body Parameters - `id: optional string` - `force: optional boolean` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/DeleteService \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## ListServices **post** `/gitpod.v1.EnvironmentAutomationService/ListServices` Lists automation services with optional filtering. Use this method to: - View all services in an environment - Filter services by reference - Monitor service status ### Examples - List environment services: Shows all services for an environment. ```yaml filter: environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] pagination: pageSize: 20 ``` - Filter by reference: Lists services matching specific references. ```yaml filter: references: ["web-server", "database"] pagination: pageSize: 20 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { environmentIds, references, roles, serviceIds }` filter contains the filter options for listing services - `environmentIds: optional array of string` environment_ids filters the response to only services of these environments - `references: optional array of string` references filters the response to only services with these references - `roles: optional array of ServiceRole` roles filters the response to only services with these roles - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `serviceIds: optional array of string` service_ids filters the response to only services with these IDs - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing services - `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 - `services: optional array of Service` - `id: string` - `environmentId: optional string` - `metadata: optional ServiceMetadata` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional ServiceSpec` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `status: optional ServiceStatus` - `failureMessage: optional string` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url contains the URL at which the service logs can be accessed. - `output: optional map[string]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: optional ServicePhase` phase is the current phase of the service. - `session: optional string` session is the current session of the service. - `statusVersion: optional string` version of the status update. Service 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. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/ListServices \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "services": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "description": "description", "name": "x", "reference": "reference", "role": "SERVICE_ROLE_UNSPECIFIED", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "commands": { "ready": "ready", "start": "x", "stop": "stop" }, "desiredPhase": "SERVICE_PHASE_UNSPECIFIED", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} }, "session": "session", "specVersion": "specVersion" }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "output": { "foo": "string" }, "phase": "SERVICE_PHASE_UNSPECIFIED", "session": "session", "statusVersion": "statusVersion" } } ] } ``` ## GetService **post** `/gitpod.v1.EnvironmentAutomationService/GetService` Gets details about a specific automation service. Use this method to: - Check service status - View service configuration - Monitor service health - Retrieve service metadata ### Examples - Get service details: Retrieves information about a specific service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Returns - `service: Service` - `id: string` - `environmentId: optional string` - `metadata: optional ServiceMetadata` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional ServiceSpec` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `status: optional ServiceStatus` - `failureMessage: optional string` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url contains the URL at which the service logs can be accessed. - `output: optional map[string]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: optional ServicePhase` phase is the current phase of the service. - `session: optional string` session is the current session of the service. - `statusVersion: optional string` version of the status update. Service 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. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/GetService \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "service": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "description": "description", "name": "x", "reference": "reference", "role": "SERVICE_ROLE_UNSPECIFIED", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "commands": { "ready": "ready", "start": "x", "stop": "stop" }, "desiredPhase": "SERVICE_PHASE_UNSPECIFIED", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} }, "session": "session", "specVersion": "specVersion" }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "output": { "foo": "string" }, "phase": "SERVICE_PHASE_UNSPECIFIED", "session": "session", "statusVersion": "statusVersion" } } } ``` ## StartService **post** `/gitpod.v1.EnvironmentAutomationService/StartService` Starts an automation service. This call does not block until the service is started. This call will not error if the service is already running or has been started. Use this method to: - Start stopped services - Resume service operations - Trigger service initialization ### Examples - Start service: Starts a previously stopped service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/StartService \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## StopService **post** `/gitpod.v1.EnvironmentAutomationService/StopService` Stops an automation service. This call does not block until the service is stopped. This call will not error if the service is already stopped or has been stopped. Use this method to: - Pause service operations - Gracefully stop services - Prepare for updates ### Examples - Stop service: Gracefully stops a running service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/StopService \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## UpdateService **post** `/gitpod.v1.EnvironmentAutomationService/UpdateService` Updates an automation service configuration. Use this method to: - Modify service commands - Update triggers - Change runtime settings - Adjust dependencies ### Examples - Update commands: Changes service start and ready commands. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" spec: commands: start: "npm run start:dev" ready: "curl -s http://localhost:8080" ``` - Update triggers: Modifies when the service starts. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" metadata: triggeredBy: trigger: - postDevcontainerStart: true - manual: true ``` ### Body Parameters - `id: optional string` - `metadata: optional object { description, name, role, triggeredBy }` - `description: optional string` - `name: optional string` - `role: optional ServiceRole` - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional object { trigger }` - `trigger: optional array of AutomationTrigger` - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional object { commands, env, runsOn }` Changing the spec of a service is a complex operation. The spec of a service can only be updated if the service is in a stopped state. If the service is running, it must be stopped first. - `commands: optional object { ready, start, stop }` - `ready: optional string` - `start: optional string` - `stop: optional string` - `env: optional array of EnvironmentVariableItem` - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `status: optional object { failureMessage, logUrl, output, 2 more }` Service status updates are only expected from the executing environment. As a client of this API you are not expected to provide this field. Updating this field requires the `environmentservice:update_status` permission. - `failureMessage: optional string` - `logUrl: optional string` - `output: optional map[string]` setting an output field to empty string will unset it. - `phase: optional ServicePhase` - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `session: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/UpdateService \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## Domain Types ### Service - `Service object { id, environmentId, metadata, 2 more }` - `id: string` - `environmentId: optional string` - `metadata: optional ServiceMetadata` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional ServiceSpec` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `status: optional ServiceStatus` - `failureMessage: optional string` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url contains the URL at which the service logs can be accessed. - `output: optional map[string]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: optional ServicePhase` phase is the current phase of the service. - `session: optional string` session is the current session of the service. - `statusVersion: optional string` version of the status update. Service 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. ### Service Metadata - `ServiceMetadata object { createdAt, creator, description, 4 more }` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` ### Service Phase - `ServicePhase = "SERVICE_PHASE_UNSPECIFIED" or "SERVICE_PHASE_STARTING" or "SERVICE_PHASE_RUNNING" or 4 more` - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` ### Service Role - `ServiceRole = "SERVICE_ROLE_UNSPECIFIED" or "SERVICE_ROLE_DEFAULT" or "SERVICE_ROLE_EDITOR" or 2 more` - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` ### Service Spec - `ServiceSpec object { commands, desiredPhase, env, 3 more }` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. ### Service Status - `ServiceStatus object { failureMessage, logUrl, output, 3 more }` - `failureMessage: optional string` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url contains the URL at which the service logs can be accessed. - `output: optional map[string]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: optional ServicePhase` phase is the current phase of the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `session: optional string` session is the current session of the service. - `statusVersion: optional string` version of the status update. Service 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. ### Service Create Response - `ServiceCreateResponse object { service }` - `service: Service` - `id: string` - `environmentId: optional string` - `metadata: optional ServiceMetadata` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional ServiceSpec` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `status: optional ServiceStatus` - `failureMessage: optional string` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url contains the URL at which the service logs can be accessed. - `output: optional map[string]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: optional ServicePhase` phase is the current phase of the service. - `session: optional string` session is the current session of the service. - `statusVersion: optional string` version of the status update. Service 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. ### Service Delete Response - `ServiceDeleteResponse = unknown` ### Service Retrieve Response - `ServiceRetrieveResponse object { service }` - `service: Service` - `id: string` - `environmentId: optional string` - `metadata: optional ServiceMetadata` - `createdAt: optional string` created_at is the time the service was created. - `creator: optional Subject` creator describes the principal who created the service. - `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"` - `description: optional string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: optional string` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: optional string` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: optional ServiceRole` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the service. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional ServiceSpec` - `commands: optional object { ready, start, stop }` commands contains the commands to start, stop and check the readiness of the service - `ready: optional string` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: optional string` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: optional string` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desiredPhase: optional ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the service. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the service should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `session: optional string` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `specVersion: optional string` version of the spec. 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.spec_version < b.spec_version then a was the spec before b. - `status: optional ServiceStatus` - `failureMessage: optional string` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url contains the URL at which the service logs can be accessed. - `output: optional map[string]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: optional ServicePhase` phase is the current phase of the service. - `session: optional string` session is the current session of the service. - `statusVersion: optional string` version of the status update. Service 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. ### Service Start Response - `ServiceStartResponse = unknown` ### Service Stop Response - `ServiceStopResponse = unknown` ### Service Update Response - `ServiceUpdateResponse = unknown` # Tasks ## CreateTask **post** `/gitpod.v1.EnvironmentAutomationService/CreateTask` Creates a new automation task. Use this method to: - Define one-off or scheduled tasks - Set up build or test automation - Configure task dependencies - Specify execution environments ### Examples - Create basic task: Creates a simple build task. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "build" name: "Build Project" description: "Builds the project artifacts" triggeredBy: - postEnvironmentStart: true spec: command: "npm run build" ``` - Create task with dependencies: Creates a task that depends on other services. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "test" name: "Run Tests" description: "Runs the test suite" spec: command: "npm test" dependsOn: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] ``` ### Body Parameters - `dependsOn: optional array of string` - `environmentId: optional string` - `metadata: optional TaskMetadata` - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created the task. - `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"` - `description: optional string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: optional string` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: optional string` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the task. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. ### Returns - `task: Task` - `id: string` - `dependsOn: optional array of string` dependencies specifies the IDs of the automations this task depends on. - `environmentId: optional string` - `metadata: optional TaskMetadata` - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created the task. - `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"` - `description: optional string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: optional string` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: optional string` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the task. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/CreateTask \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ], "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "description": "description", "name": "x", "reference": "reference", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ``` ## DeleteTask **post** `/gitpod.v1.EnvironmentAutomationService/DeleteTask` Deletes an automation task. Use this method to: - Remove unused tasks - Clean up task configurations - Delete obsolete automations ### Examples - Delete task: Removes a task and its configuration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/DeleteTask \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## ListTasks **post** `/gitpod.v1.EnvironmentAutomationService/ListTasks` Lists automation tasks with optional filtering. Use this method to: - View all tasks in an environment - Filter tasks by reference - Monitor task status ### Examples - List environment tasks: Shows all tasks for an environment. ```yaml filter: environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] pagination: pageSize: 20 ``` - Filter by reference: Lists tasks matching specific references. ```yaml filter: references: ["build", "test"] pagination: pageSize: 20 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { environmentIds, references, taskIds }` filter contains the filter options for listing tasks - `environmentIds: optional array of string` environment_ids filters the response to only tasks of these environments - `references: optional array of string` references filters the response to only services with these references - `taskIds: optional array of string` task_ids filters the response to only tasks with these IDs - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing tasks - `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 - `tasks: optional array of Task` - `id: string` - `dependsOn: optional array of string` dependencies specifies the IDs of the automations this task depends on. - `environmentId: optional string` - `metadata: optional TaskMetadata` - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created the task. - `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"` - `description: optional string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: optional string` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: optional string` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the task. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/ListTasks \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "tasks": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ], "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "description": "description", "name": "x", "reference": "reference", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } ] } ``` ## GetTask **post** `/gitpod.v1.EnvironmentAutomationService/GetTask` Gets details about a specific automation task. Use this method to: - Check task configuration - View task dependencies - Monitor task status ### Examples - Get task details: Retrieves information about a specific task. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Returns - `task: Task` - `id: string` - `dependsOn: optional array of string` dependencies specifies the IDs of the automations this task depends on. - `environmentId: optional string` - `metadata: optional TaskMetadata` - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created the task. - `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"` - `description: optional string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: optional string` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: optional string` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the task. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/GetTask \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ], "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "description": "description", "name": "x", "reference": "reference", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ``` ## StartTask **post** `/gitpod.v1.EnvironmentAutomationService/StartTask` Starts a task by creating a new task execution. This call does not block until the task is started; the task will be started asynchronously. Use this method to: - Trigger task execution - Run one-off tasks - Start scheduled tasks immediately ### Examples - Start task: Creates a new execution of a task. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Returns - `taskExecution: TaskExecution` - `id: string` - `metadata: optional TaskExecutionMetadata` - `completedAt: optional string` completed_at is the time the task execution was done. - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created/started the task run. - `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"` - `environmentId: optional string` environment_id is the ID of the environment in which the task run is executed. - `startedAt: optional string` started_at is the time the task execution actually started to run. - `startedBy: optional string` started_by describes the trigger that started the task execution. - `taskId: optional string` task_id is the ID of the main task being executed. - `spec: optional TaskExecutionSpec` - `desiredPhase: optional TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: optional array of object { steps }` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: optional array of object { id, dependsOn, label, 2 more }` - `id: optional string` ID is the ID of the execution step - `dependsOn: optional array of string` - `label: optional string` - `serviceId: optional string` - `task: optional object { id, spec }` - `id: optional string` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `status: optional TaskExecutionStatus` - `failureMessage: optional string` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: optional TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `statusVersion: optional string` version of the status update. Task executions 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. - `steps: optional array of object { id, failureMessage, output, phase }` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: optional string` ID is the ID of the execution step - `failureMessage: optional string` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: optional map[string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: optional TaskExecutionPhase` phase is the current phase of the execution step ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/StartTask \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "taskExecution": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "completedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "startedAt": "2019-12-27T18:11:19.117Z", "startedBy": "startedBy", "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "plan": [ { "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "string" ], "label": "label", "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ] } ] }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "statusVersion": "statusVersion", "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "output": { "foo": "string" }, "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED" } ] } } } ``` ## UpdateTask **post** `/gitpod.v1.EnvironmentAutomationService/UpdateTask` Updates an automation task configuration. Use this method to: - Modify task commands - Update task triggers - Change dependencies - Adjust execution settings ### Examples - Update command: Changes the task's command. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" spec: command: "npm run test:coverage" ``` - Update triggers: Modifies when the task runs. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" metadata: triggeredBy: trigger: - postEnvironmentStart: true ``` ### Body Parameters - `id: optional string` - `dependsOn: optional array of string` dependencies specifies the IDs of the automations this task depends on. - `metadata: optional object { description, name, triggeredBy }` - `description: optional string` - `name: optional string` - `triggeredBy: optional object { trigger }` - `trigger: optional array of AutomationTrigger` - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional object { command, env, runsOn }` - `command: optional string` - `env: optional array of EnvironmentVariableItem` - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/UpdateTask \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## Domain Types ### Task Create Response - `TaskCreateResponse object { task }` - `task: Task` - `id: string` - `dependsOn: optional array of string` dependencies specifies the IDs of the automations this task depends on. - `environmentId: optional string` - `metadata: optional TaskMetadata` - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created the task. - `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"` - `description: optional string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: optional string` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: optional string` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the task. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. ### Task Delete Response - `TaskDeleteResponse = unknown` ### Task Retrieve Response - `TaskRetrieveResponse object { task }` - `task: Task` - `id: string` - `dependsOn: optional array of string` dependencies specifies the IDs of the automations this task depends on. - `environmentId: optional string` - `metadata: optional TaskMetadata` - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created the task. - `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"` - `description: optional string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: optional string` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: optional string` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggeredBy: optional array of AutomationTrigger` triggered_by is a list of trigger that start the task. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. ### Task Start Response - `TaskStartResponse object { taskExecution }` - `taskExecution: TaskExecution` - `id: string` - `metadata: optional TaskExecutionMetadata` - `completedAt: optional string` completed_at is the time the task execution was done. - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created/started the task run. - `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"` - `environmentId: optional string` environment_id is the ID of the environment in which the task run is executed. - `startedAt: optional string` started_at is the time the task execution actually started to run. - `startedBy: optional string` started_by describes the trigger that started the task execution. - `taskId: optional string` task_id is the ID of the main task being executed. - `spec: optional TaskExecutionSpec` - `desiredPhase: optional TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: optional array of object { steps }` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: optional array of object { id, dependsOn, label, 2 more }` - `id: optional string` ID is the ID of the execution step - `dependsOn: optional array of string` - `label: optional string` - `serviceId: optional string` - `task: optional object { id, spec }` - `id: optional string` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `status: optional TaskExecutionStatus` - `failureMessage: optional string` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: optional TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `statusVersion: optional string` version of the status update. Task executions 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. - `steps: optional array of object { id, failureMessage, output, phase }` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: optional string` ID is the ID of the execution step - `failureMessage: optional string` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: optional map[string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: optional TaskExecutionPhase` phase is the current phase of the execution step ### Task Update Response - `TaskUpdateResponse = unknown` # Executions ## ListTaskExecutions **post** `/gitpod.v1.EnvironmentAutomationService/ListTaskExecutions` Lists executions of automation tasks. Use this method to: - View task execution history - Monitor running tasks - Track task completion status ### Examples - List all executions: Shows execution history for all tasks. ```yaml filter: environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] pagination: pageSize: 20 ``` - Filter by phase: Lists executions in specific phases. ```yaml filter: phases: ["TASK_EXECUTION_PHASE_RUNNING", "TASK_EXECUTION_PHASE_FAILED"] pagination: pageSize: 20 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { environmentIds, phases, taskIds, taskReferences }` filter contains the filter options for listing task runs - `environmentIds: optional array of string` environment_ids filters the response to only task runs of these environments - `phases: optional array of TaskExecutionPhase` phases filters the response to only task runs in these phases - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `taskIds: optional array of string` task_ids filters the response to only task runs of these tasks - `taskReferences: optional array of string` task_references filters the response to only task runs with this reference - `pagination: optional object { token, pageSize }` pagination contains the pagination options for listing task runs - `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 - `taskExecutions: optional array of TaskExecution` - `id: string` - `metadata: optional TaskExecutionMetadata` - `completedAt: optional string` completed_at is the time the task execution was done. - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created/started the task run. - `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"` - `environmentId: optional string` environment_id is the ID of the environment in which the task run is executed. - `startedAt: optional string` started_at is the time the task execution actually started to run. - `startedBy: optional string` started_by describes the trigger that started the task execution. - `taskId: optional string` task_id is the ID of the main task being executed. - `spec: optional TaskExecutionSpec` - `desiredPhase: optional TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: optional array of object { steps }` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: optional array of object { id, dependsOn, label, 2 more }` - `id: optional string` ID is the ID of the execution step - `dependsOn: optional array of string` - `label: optional string` - `serviceId: optional string` - `task: optional object { id, spec }` - `id: optional string` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `status: optional TaskExecutionStatus` - `failureMessage: optional string` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: optional TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `statusVersion: optional string` version of the status update. Task executions 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. - `steps: optional array of object { id, failureMessage, output, phase }` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: optional string` ID is the ID of the execution step - `failureMessage: optional string` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: optional map[string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: optional TaskExecutionPhase` phase is the current phase of the execution step ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/ListTaskExecutions \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "taskExecutions": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "completedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "startedAt": "2019-12-27T18:11:19.117Z", "startedBy": "startedBy", "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "plan": [ { "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "string" ], "label": "label", "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ] } ] }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "statusVersion": "statusVersion", "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "output": { "foo": "string" }, "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED" } ] } } ] } ``` ## GetTaskExecution **post** `/gitpod.v1.EnvironmentAutomationService/GetTaskExecution` Gets details about a specific task execution. Use this method to: - Monitor execution progress - View execution logs - Check execution status - Debug failed executions ### Examples - Get execution details: Retrieves information about a specific task execution. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Returns - `taskExecution: TaskExecution` - `id: string` - `metadata: optional TaskExecutionMetadata` - `completedAt: optional string` completed_at is the time the task execution was done. - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created/started the task run. - `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"` - `environmentId: optional string` environment_id is the ID of the environment in which the task run is executed. - `startedAt: optional string` started_at is the time the task execution actually started to run. - `startedBy: optional string` started_by describes the trigger that started the task execution. - `taskId: optional string` task_id is the ID of the main task being executed. - `spec: optional TaskExecutionSpec` - `desiredPhase: optional TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: optional array of object { steps }` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: optional array of object { id, dependsOn, label, 2 more }` - `id: optional string` ID is the ID of the execution step - `dependsOn: optional array of string` - `label: optional string` - `serviceId: optional string` - `task: optional object { id, spec }` - `id: optional string` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `status: optional TaskExecutionStatus` - `failureMessage: optional string` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: optional TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `statusVersion: optional string` version of the status update. Task executions 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. - `steps: optional array of object { id, failureMessage, output, phase }` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: optional string` ID is the ID of the execution step - `failureMessage: optional string` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: optional map[string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: optional TaskExecutionPhase` phase is the current phase of the execution step ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/GetTaskExecution \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "taskExecution": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "completedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "startedAt": "2019-12-27T18:11:19.117Z", "startedBy": "startedBy", "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "plan": [ { "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "string" ], "label": "label", "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ] } ] }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "statusVersion": "statusVersion", "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "output": { "foo": "string" }, "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED" } ] } } } ``` ## StopTaskExecution **post** `/gitpod.v1.EnvironmentAutomationService/StopTaskExecution` Stops a running task execution. Use this method to: - Cancel long-running tasks - Stop failed executions - Interrupt task processing ### Examples - Stop execution: Stops a running task execution. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `id: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/StopTaskExecution \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## Domain Types ### Execution Retrieve Response - `ExecutionRetrieveResponse object { taskExecution }` - `taskExecution: TaskExecution` - `id: string` - `metadata: optional TaskExecutionMetadata` - `completedAt: optional string` completed_at is the time the task execution was done. - `createdAt: optional string` created_at is the time the task was created. - `creator: optional Subject` creator describes the principal who created/started the task run. - `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"` - `environmentId: optional string` environment_id is the ID of the environment in which the task run is executed. - `startedAt: optional string` started_at is the time the task execution actually started to run. - `startedBy: optional string` started_by describes the trigger that started the task execution. - `taskId: optional string` task_id is the ID of the main task being executed. - `spec: optional TaskExecutionSpec` - `desiredPhase: optional TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: optional array of object { steps }` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: optional array of object { id, dependsOn, label, 2 more }` - `id: optional string` ID is the ID of the execution step - `dependsOn: optional array of string` - `label: optional string` - `serviceId: optional string` - `task: optional object { id, spec }` - `id: optional string` - `spec: optional TaskSpec` - `command: optional string` command contains the command the task should execute - `env: optional array of EnvironmentVariableItem` env specifies environment variables for the task. - `name: optional string` name is the environment variable name. - `value: optional string` value is a literal string value. - `valueFrom: optional EnvironmentVariableSource` value_from specifies a source for the value. - `secretRef: SecretRef` secret_ref references a secret by ID. - `id: optional string` id is the UUID of the secret to reference. - `runsOn: optional RunsOn` runs_on specifies the environment the task should run on. - `docker: optional object { environment, image }` - `environment: optional array of string` - `image: optional string` - `machine: optional unknown` Machine runs the service/task directly on the VM/machine level. - `status: optional TaskExecutionStatus` - `failureMessage: optional string` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `logUrl: optional string` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: optional TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `statusVersion: optional string` version of the status update. Task executions 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. - `steps: optional array of object { id, failureMessage, output, phase }` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: optional string` ID is the ID of the execution step - `failureMessage: optional string` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: optional map[string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: optional TaskExecutionPhase` phase is the current phase of the execution step ### Execution Stop Response - `ExecutionStopResponse = unknown` # Classes ## ListEnvironmentClasses **post** `/gitpod.v1.EnvironmentService/ListEnvironmentClasses` Lists available environment classes with their specifications and resource limits. Use this method to understand what types of environments you can create and their capabilities. Environment classes define the compute resources and features available to your environments. ### Examples - List all available classes: Retrieves a list of all environment classes with their specifications. ```yaml {} ``` 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.EnvironmentService/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" } } ```