# Environments ## CreateEnvironment `client.Environments.New(ctx, body) (*EnvironmentNewResponse, error)` **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" ``` ### Parameters - `body EnvironmentNewParams` - `Name param.Field[string]` name is a user-defined identifier for the environment. If not specified, the system will generate a name. - `SessionID param.Field[string]` session_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly. - `Spec param.Field[EnvironmentSpec]` spec is the configuration of the environment that's required for the to start the environment ### Returns - `type EnvironmentNewResponse struct{…}` - `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 EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `Annotations map[string, string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `ArchivedAt Time` Time when the Environment was archived. If not set, the environment is not archived. - `CreatedAt Time` Time when the Environment was created. - `Creator Subject` creator is the identity of the creator of the environment - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `LastStartedAt Time` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `LockdownAt Time` 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 string` name is the name of the environment as specified by the user - `OrganizationID string` organization_id is the ID of the organization that contains the environment - `OriginalContextURL string` original_context_url is the normalized URL from which the environment was created - `PrebuildID 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 string` If the Environment was started from a project, the project_id will reference the project. - `Role EnvironmentRole` role is the role of the environment - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` - `RunnerID string` Runner is the ID of the runner that runs this environment. - `Spec EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `Admission AdmissionLevel` admission controlls who can access the environment and its ports. - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` - `AutomationsFile EnvironmentSpecAutomationsFile` automations_file is the automations file spec of the environment - `AutomationsFilePath 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 string` - `TriggerFilter []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 bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Content EnvironmentSpecContent` content is the content spec of the environment - `GitEmail string` The Git email address - `GitUsername string` The Git username - `Initializer EnvironmentInitializer` initializer configures how the environment is to be initialized - `Specs []EnvironmentInitializerSpec` - `ContextURL EnvironmentInitializerSpecsContextURL` - `URL string` url is the URL from which the environment is created - `Git EnvironmentInitializerSpecsGit` - `CheckoutLocation string` a path relative to the environment root in which the code will be checked out to - `CloneTarget string` the value for the clone target mode - use depends on the target mode - `RemoteUri string` remote_uri is the Git remote origin - `TargetMode EnvironmentInitializerSpecsGitTargetMode` the target mode determines what gets checked out - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeUnspecified EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_UNSPECIFIED"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteHead EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_HEAD"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteCommit EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_COMMIT"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeLocalBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_LOCAL_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteTag EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_TAG"` - `UpstreamRemoteUri string` upstream_Remote_uri is the fork upstream of a repository - `Session string` - `DesiredPhase EnvironmentPhase` Phase is the desired phase of the environment - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `Devcontainer EnvironmentSpecDevcontainer` devcontainer is the devcontainer spec of the environment - `DefaultDevcontainerImage string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `DevcontainerFilePath 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 EnvironmentSpecDevcontainerDotfiles` 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 EnvironmentSpecDevcontainerLifecycleStage` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageUnspecified EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_UNSPECIFIED"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageFull EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_FULL"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStagePrebuild EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_PREBUILD"` - `Session string` - `KernelControlsConfig KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active - `Machine EnvironmentSpecMachine` machine is the machine spec of the environment - `Class string` Class denotes the class of the environment we ought to start - `Session string` - `Ports []EnvironmentSpecPort` ports is the set of ports which ought to be exposed to your network - `Admission AdmissionLevel` policy of this port - `Name string` name of this port - `Port int64` port number - `Protocol EnvironmentSpecPortsProtocol` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `const EnvironmentSpecPortsProtocolProtocolUnspecified EnvironmentSpecPortsProtocol = "PROTOCOL_UNSPECIFIED"` - `const EnvironmentSpecPortsProtocolProtocolHTTP EnvironmentSpecPortsProtocol = "PROTOCOL_HTTP"` - `const EnvironmentSpecPortsProtocolProtocolHTTPS EnvironmentSpecPortsProtocol = "PROTOCOL_HTTPS"` - `Secrets []EnvironmentSpecSecret` secrets are confidential data that is mounted into the environment - `ID string` id is the unique identifier of the secret. - `APIOnly bool` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `ContainerRegistryBasicAuthHost string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `CredentialProxy EnvironmentSpecSecretsCredentialProxy` 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 EnvironmentSpecSecretsCredentialProxyFormat` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `const EnvironmentSpecSecretsCredentialProxyFormatFormatUnspecified EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_UNSPECIFIED"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatPlain EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_PLAIN"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatBase64 EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_BASE64"` - `Header string` header is the HTTP header name to inject (e.g. "Authorization"). - `TargetHosts []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 string` - `FilePath string` file_path is the path inside the devcontainer where the secret is mounted - `GitCredentialHost string` - `Name string` name is the human readable description of the secret - `Scope EnvironmentSpecSecretsScope` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `const EnvironmentSpecSecretsScopeScopeUnspecified EnvironmentSpecSecretsScope = "SCOPE_UNSPECIFIED"` - `const EnvironmentSpecSecretsScopeScopeOrganization EnvironmentSpecSecretsScope = "SCOPE_ORGANIZATION"` - `const EnvironmentSpecSecretsScopeScopeProject EnvironmentSpecSecretsScope = "SCOPE_PROJECT"` - `const EnvironmentSpecSecretsScopeScopeUser EnvironmentSpecSecretsScope = "SCOPE_USER"` - `const EnvironmentSpecSecretsScopeScopeServiceAccount EnvironmentSpecSecretsScope = "SCOPE_SERVICE_ACCOUNT"` - `const EnvironmentSpecSecretsScopeScopeRunner EnvironmentSpecSecretsScope = "SCOPE_RUNNER"` - `Session string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `Source string` source is the source of the secret, for now control-plane or runner - `SourceRef string` source_ref into the source, in case of control-plane this is uuid of the secret - `SpecVersion 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 []EnvironmentSpecSSHPublicKey` ssh_public_keys are the public keys used to ssh into the environment - `ID string` id is the unique identifier of the public key - `Value string` value is the actual public key in the public key file format - `Timeout EnvironmentSpecTimeout` Timeout configures the environment timeout - `Disconnected 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 string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `Status EnvironmentStatus` Status is the current status of the environment - `ActivitySignal EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `Source string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `Timestamp Time` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `AutomationsFile EnvironmentStatusAutomationsFile` automations_file contains the status of the automations file. - `AutomationsFilePath string` automations_file_path is the path to the automations file relative to the repo root. - `AutomationsFilePresence EnvironmentStatusAutomationsFileAutomationsFilePresence` automations_file_presence indicates how an automations file is present in the environment. - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceUnspecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceAbsent EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_ABSENT"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceDiscovered EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceSpecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `Phase EnvironmentStatusAutomationsFilePhase` phase is the current phase of the automations file. - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnspecified EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseCreating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseInitializing EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseReady EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUpdating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseFailed EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnavailable EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the automations file session that is currently applied in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `Content EnvironmentStatusContent` content contains the status of the environment content. - `ContentLocationInMachine string` content_location_in_machine is the location of the content in the machine - `FailureMessage string` failure_message contains the reason the content initialization failed. - `Git EnvironmentStatusContentGit` 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 string` branch is branch we're currently on - `ChangedFiles []EnvironmentStatusContentGitChangedFile` changed_files is an array of changed files in the environment, possibly truncated - `ChangeType EnvironmentStatusContentGitChangedFilesChangeType` ChangeType is the type of change that happened to the file - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUnspecified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNSPECIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeAdded EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_ADDED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeModified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_MODIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeDeleted EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_DELETED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeRenamed EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_RENAMED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeCopied EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_COPIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUpdatedButUnmerged EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UPDATED_BUT_UNMERGED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUntracked EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNTRACKED"` - `OldPath string` old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `Path string` path is the path of the file - `CloneURL string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `LatestCommit string` latest_commit is the most recent commit on the current branch - `TotalChangedFiles int64` - `TotalUnpushedCommits int64` the total number of unpushed changes - `UnpushedCommits []string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `Phase EnvironmentStatusContentPhase` phase is the current phase of the environment content - `const EnvironmentStatusContentPhaseContentPhaseUnspecified EnvironmentStatusContentPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusContentPhaseContentPhaseCreating EnvironmentStatusContentPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusContentPhaseContentPhaseInitializing EnvironmentStatusContentPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusContentPhaseContentPhaseReady EnvironmentStatusContentPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusContentPhaseContentPhaseUpdating EnvironmentStatusContentPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusContentPhaseContentPhaseFailed EnvironmentStatusContentPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusContentPhaseContentPhaseUnavailable EnvironmentStatusContentPhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `Devcontainer EnvironmentStatusDevcontainer` devcontainer contains the status of the devcontainer. - `ContainerID string` container_id is the ID of the container. - `ContainerName string` container_name is the name of the container that is used to connect to the devcontainer - `DevcontainerconfigInSync bool` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `DevcontainerFilePath string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `DevcontainerFilePresence EnvironmentStatusDevcontainerDevcontainerFilePresence` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceUnspecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceGenerated EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_GENERATED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceDiscovered EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceSpecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the devcontainer failed to operate. - `Phase EnvironmentStatusDevcontainerPhase` phase is the current phase of the devcontainer - `const EnvironmentStatusDevcontainerPhasePhaseUnspecified EnvironmentStatusDevcontainerPhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerPhasePhaseCreating EnvironmentStatusDevcontainerPhase = "PHASE_CREATING"` - `const EnvironmentStatusDevcontainerPhasePhaseRunning EnvironmentStatusDevcontainerPhase = "PHASE_RUNNING"` - `const EnvironmentStatusDevcontainerPhasePhaseStopped EnvironmentStatusDevcontainerPhase = "PHASE_STOPPED"` - `const EnvironmentStatusDevcontainerPhasePhaseFailed EnvironmentStatusDevcontainerPhase = "PHASE_FAILED"` - `RemoteUser string` remote_user is the user that is used to connect to the devcontainer - `RemoteWorkspaceFolder string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `SecretsInSync bool` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `Session string` session is the session that is currently active in the devcontainer. - `WarningMessage string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `EnvironmentURLs EnvironmentStatusEnvironmentURLs` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `Logs string` logs is the URL at which the environment logs can be accessed. - `Ops string` ops is the URL at which the environment ops service can be accessed. - `Ports []EnvironmentStatusEnvironmentURLsPort` - `Port int64` port is the port number of the environment port - `URL string` url is the URL at which the environment port can be accessed - `SSH EnvironmentStatusEnvironmentURLsSSH` SSH is the URL at which the environment can be accessed via SSH. - `URL string` - `SupportBundle string` support_bundle is the URL at which the environment support bundle can be accessed. - `FailureMessage []string` failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `Machine EnvironmentStatusMachine` machine contains the status of the environment machine - `FailureMessage string` failure_message contains the reason the machine failed to operate. - `Phase EnvironmentStatusMachinePhase` phase is the current phase of the environment machine - `const EnvironmentStatusMachinePhasePhaseUnspecified EnvironmentStatusMachinePhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusMachinePhasePhaseCreating EnvironmentStatusMachinePhase = "PHASE_CREATING"` - `const EnvironmentStatusMachinePhasePhaseStarting EnvironmentStatusMachinePhase = "PHASE_STARTING"` - `const EnvironmentStatusMachinePhasePhaseRunning EnvironmentStatusMachinePhase = "PHASE_RUNNING"` - `const EnvironmentStatusMachinePhasePhaseStopping EnvironmentStatusMachinePhase = "PHASE_STOPPING"` - `const EnvironmentStatusMachinePhasePhaseStopped EnvironmentStatusMachinePhase = "PHASE_STOPPED"` - `const EnvironmentStatusMachinePhasePhaseDeleting EnvironmentStatusMachinePhase = "PHASE_DELETING"` - `const EnvironmentStatusMachinePhasePhaseDeleted EnvironmentStatusMachinePhase = "PHASE_DELETED"` - `Session string` session is the session that is currently active in the machine. - `Timeout string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `Versions EnvironmentStatusMachineVersions` versions contains the versions of components in the machine. - `AmiID string` - `SupervisorCommit string` - `SupervisorVersion string` - `WarningMessage string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `Phase EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `RunnerAck EnvironmentStatusRunnerAck` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `Message string` - `SpecVersion string` - `StatusCode EnvironmentStatusRunnerAckStatusCode` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeUnspecified EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_UNSPECIFIED"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeOk EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_OK"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeInvalidResource EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_INVALID_RESOURCE"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeFailedPrecondition EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_FAILED_PRECONDITION"` - `Secrets []EnvironmentStatusSecret` secrets contains the status of the environment secrets - `ID string` id is the unique identifier of the secret. - `FailureMessage string` failure_message contains the reason the secret failed to be materialize. - `Phase EnvironmentStatusSecretsPhase` - `const EnvironmentStatusSecretsPhaseContentPhaseUnspecified EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSecretsPhaseContentPhaseCreating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseInitializing EnvironmentStatusSecretsPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSecretsPhaseContentPhaseReady EnvironmentStatusSecretsPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSecretsPhaseContentPhaseUpdating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseFailed EnvironmentStatusSecretsPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSecretsPhaseContentPhaseUnavailable EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNAVAILABLE"` - `SecretName string` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `SSHPublicKeys []EnvironmentStatusSSHPublicKey` ssh_public_keys contains the status of the environment ssh public keys - `ID string` id is the unique identifier of the public key - `Phase EnvironmentStatusSSHPublicKeysPhase` phase is the current phase of the public key - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnspecified EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseCreating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseInitializing EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseReady EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUpdating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseFailed EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnavailable EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNAVAILABLE"` - `StatusVersion string` version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `WarningMessage []string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) environment, err := client.Environments.New(context.TODO(), gitpod.EnvironmentNewParams{ Spec: gitpod.F(gitpod.EnvironmentSpecParam{ Content: gitpod.F(gitpod.EnvironmentSpecContentParam{ Initializer: gitpod.F(gitpod.EnvironmentInitializerParam{ Specs: gitpod.F([]gitpod.EnvironmentInitializerSpecParam{gitpod.EnvironmentInitializerSpecParam{ ContextURL: gitpod.F(gitpod.EnvironmentInitializerSpecsContextURLParam{ URL: gitpod.F("https://github.com/gitpod-io/gitpod"), }), }}), }), }), Machine: gitpod.F(gitpod.EnvironmentSpecMachineParam{ Class: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", environment.Environment) } ``` #### 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 `client.Environments.NewEnvironmentToken(ctx, body) (*EnvironmentNewEnvironmentTokenResponse, error)` **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" ``` ### Parameters - `body EnvironmentNewEnvironmentTokenParams` - `EnvironmentID param.Field[string]` environment_id specifies the environment for which the access token should be created. ### Returns - `type EnvironmentNewEnvironmentTokenResponse struct{…}` - `AccessToken string` access_token is the token that can be used for environment authentication ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.NewEnvironmentToken(context.TODO(), gitpod.EnvironmentNewEnvironmentTokenParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.AccessToken) } ``` #### Response ```json { "accessToken": "accessToken" } ``` ## CreateEnvironmentFromProject `client.Environments.NewFromProject(ctx, body) (*EnvironmentNewFromProjectResponse, error)` **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 ``` ### Parameters - `body EnvironmentNewFromProjectParams` - `Name param.Field[string]` name is a user-defined identifier for the environment. If not specified, the system will generate a name. - `ProjectID param.Field[string]` - `SessionID param.Field[string]` session_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly. - `Spec param.Field[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 ### Returns - `type EnvironmentNewFromProjectResponse struct{…}` - `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 EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `Annotations map[string, string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `ArchivedAt Time` Time when the Environment was archived. If not set, the environment is not archived. - `CreatedAt Time` Time when the Environment was created. - `Creator Subject` creator is the identity of the creator of the environment - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `LastStartedAt Time` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `LockdownAt Time` 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 string` name is the name of the environment as specified by the user - `OrganizationID string` organization_id is the ID of the organization that contains the environment - `OriginalContextURL string` original_context_url is the normalized URL from which the environment was created - `PrebuildID 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 string` If the Environment was started from a project, the project_id will reference the project. - `Role EnvironmentRole` role is the role of the environment - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` - `RunnerID string` Runner is the ID of the runner that runs this environment. - `Spec EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `Admission AdmissionLevel` admission controlls who can access the environment and its ports. - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` - `AutomationsFile EnvironmentSpecAutomationsFile` automations_file is the automations file spec of the environment - `AutomationsFilePath 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 string` - `TriggerFilter []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 bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Content EnvironmentSpecContent` content is the content spec of the environment - `GitEmail string` The Git email address - `GitUsername string` The Git username - `Initializer EnvironmentInitializer` initializer configures how the environment is to be initialized - `Specs []EnvironmentInitializerSpec` - `ContextURL EnvironmentInitializerSpecsContextURL` - `URL string` url is the URL from which the environment is created - `Git EnvironmentInitializerSpecsGit` - `CheckoutLocation string` a path relative to the environment root in which the code will be checked out to - `CloneTarget string` the value for the clone target mode - use depends on the target mode - `RemoteUri string` remote_uri is the Git remote origin - `TargetMode EnvironmentInitializerSpecsGitTargetMode` the target mode determines what gets checked out - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeUnspecified EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_UNSPECIFIED"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteHead EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_HEAD"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteCommit EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_COMMIT"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeLocalBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_LOCAL_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteTag EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_TAG"` - `UpstreamRemoteUri string` upstream_Remote_uri is the fork upstream of a repository - `Session string` - `DesiredPhase EnvironmentPhase` Phase is the desired phase of the environment - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `Devcontainer EnvironmentSpecDevcontainer` devcontainer is the devcontainer spec of the environment - `DefaultDevcontainerImage string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `DevcontainerFilePath 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 EnvironmentSpecDevcontainerDotfiles` 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 EnvironmentSpecDevcontainerLifecycleStage` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageUnspecified EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_UNSPECIFIED"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageFull EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_FULL"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStagePrebuild EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_PREBUILD"` - `Session string` - `KernelControlsConfig KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active - `Machine EnvironmentSpecMachine` machine is the machine spec of the environment - `Class string` Class denotes the class of the environment we ought to start - `Session string` - `Ports []EnvironmentSpecPort` ports is the set of ports which ought to be exposed to your network - `Admission AdmissionLevel` policy of this port - `Name string` name of this port - `Port int64` port number - `Protocol EnvironmentSpecPortsProtocol` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `const EnvironmentSpecPortsProtocolProtocolUnspecified EnvironmentSpecPortsProtocol = "PROTOCOL_UNSPECIFIED"` - `const EnvironmentSpecPortsProtocolProtocolHTTP EnvironmentSpecPortsProtocol = "PROTOCOL_HTTP"` - `const EnvironmentSpecPortsProtocolProtocolHTTPS EnvironmentSpecPortsProtocol = "PROTOCOL_HTTPS"` - `Secrets []EnvironmentSpecSecret` secrets are confidential data that is mounted into the environment - `ID string` id is the unique identifier of the secret. - `APIOnly bool` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `ContainerRegistryBasicAuthHost string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `CredentialProxy EnvironmentSpecSecretsCredentialProxy` 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 EnvironmentSpecSecretsCredentialProxyFormat` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `const EnvironmentSpecSecretsCredentialProxyFormatFormatUnspecified EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_UNSPECIFIED"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatPlain EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_PLAIN"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatBase64 EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_BASE64"` - `Header string` header is the HTTP header name to inject (e.g. "Authorization"). - `TargetHosts []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 string` - `FilePath string` file_path is the path inside the devcontainer where the secret is mounted - `GitCredentialHost string` - `Name string` name is the human readable description of the secret - `Scope EnvironmentSpecSecretsScope` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `const EnvironmentSpecSecretsScopeScopeUnspecified EnvironmentSpecSecretsScope = "SCOPE_UNSPECIFIED"` - `const EnvironmentSpecSecretsScopeScopeOrganization EnvironmentSpecSecretsScope = "SCOPE_ORGANIZATION"` - `const EnvironmentSpecSecretsScopeScopeProject EnvironmentSpecSecretsScope = "SCOPE_PROJECT"` - `const EnvironmentSpecSecretsScopeScopeUser EnvironmentSpecSecretsScope = "SCOPE_USER"` - `const EnvironmentSpecSecretsScopeScopeServiceAccount EnvironmentSpecSecretsScope = "SCOPE_SERVICE_ACCOUNT"` - `const EnvironmentSpecSecretsScopeScopeRunner EnvironmentSpecSecretsScope = "SCOPE_RUNNER"` - `Session string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `Source string` source is the source of the secret, for now control-plane or runner - `SourceRef string` source_ref into the source, in case of control-plane this is uuid of the secret - `SpecVersion 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 []EnvironmentSpecSSHPublicKey` ssh_public_keys are the public keys used to ssh into the environment - `ID string` id is the unique identifier of the public key - `Value string` value is the actual public key in the public key file format - `Timeout EnvironmentSpecTimeout` Timeout configures the environment timeout - `Disconnected 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 string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `Status EnvironmentStatus` Status is the current status of the environment - `ActivitySignal EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `Source string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `Timestamp Time` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `AutomationsFile EnvironmentStatusAutomationsFile` automations_file contains the status of the automations file. - `AutomationsFilePath string` automations_file_path is the path to the automations file relative to the repo root. - `AutomationsFilePresence EnvironmentStatusAutomationsFileAutomationsFilePresence` automations_file_presence indicates how an automations file is present in the environment. - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceUnspecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceAbsent EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_ABSENT"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceDiscovered EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceSpecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `Phase EnvironmentStatusAutomationsFilePhase` phase is the current phase of the automations file. - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnspecified EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseCreating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseInitializing EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseReady EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUpdating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseFailed EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnavailable EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the automations file session that is currently applied in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `Content EnvironmentStatusContent` content contains the status of the environment content. - `ContentLocationInMachine string` content_location_in_machine is the location of the content in the machine - `FailureMessage string` failure_message contains the reason the content initialization failed. - `Git EnvironmentStatusContentGit` 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 string` branch is branch we're currently on - `ChangedFiles []EnvironmentStatusContentGitChangedFile` changed_files is an array of changed files in the environment, possibly truncated - `ChangeType EnvironmentStatusContentGitChangedFilesChangeType` ChangeType is the type of change that happened to the file - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUnspecified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNSPECIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeAdded EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_ADDED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeModified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_MODIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeDeleted EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_DELETED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeRenamed EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_RENAMED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeCopied EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_COPIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUpdatedButUnmerged EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UPDATED_BUT_UNMERGED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUntracked EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNTRACKED"` - `OldPath string` old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `Path string` path is the path of the file - `CloneURL string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `LatestCommit string` latest_commit is the most recent commit on the current branch - `TotalChangedFiles int64` - `TotalUnpushedCommits int64` the total number of unpushed changes - `UnpushedCommits []string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `Phase EnvironmentStatusContentPhase` phase is the current phase of the environment content - `const EnvironmentStatusContentPhaseContentPhaseUnspecified EnvironmentStatusContentPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusContentPhaseContentPhaseCreating EnvironmentStatusContentPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusContentPhaseContentPhaseInitializing EnvironmentStatusContentPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusContentPhaseContentPhaseReady EnvironmentStatusContentPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusContentPhaseContentPhaseUpdating EnvironmentStatusContentPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusContentPhaseContentPhaseFailed EnvironmentStatusContentPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusContentPhaseContentPhaseUnavailable EnvironmentStatusContentPhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `Devcontainer EnvironmentStatusDevcontainer` devcontainer contains the status of the devcontainer. - `ContainerID string` container_id is the ID of the container. - `ContainerName string` container_name is the name of the container that is used to connect to the devcontainer - `DevcontainerconfigInSync bool` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `DevcontainerFilePath string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `DevcontainerFilePresence EnvironmentStatusDevcontainerDevcontainerFilePresence` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceUnspecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceGenerated EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_GENERATED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceDiscovered EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceSpecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the devcontainer failed to operate. - `Phase EnvironmentStatusDevcontainerPhase` phase is the current phase of the devcontainer - `const EnvironmentStatusDevcontainerPhasePhaseUnspecified EnvironmentStatusDevcontainerPhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerPhasePhaseCreating EnvironmentStatusDevcontainerPhase = "PHASE_CREATING"` - `const EnvironmentStatusDevcontainerPhasePhaseRunning EnvironmentStatusDevcontainerPhase = "PHASE_RUNNING"` - `const EnvironmentStatusDevcontainerPhasePhaseStopped EnvironmentStatusDevcontainerPhase = "PHASE_STOPPED"` - `const EnvironmentStatusDevcontainerPhasePhaseFailed EnvironmentStatusDevcontainerPhase = "PHASE_FAILED"` - `RemoteUser string` remote_user is the user that is used to connect to the devcontainer - `RemoteWorkspaceFolder string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `SecretsInSync bool` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `Session string` session is the session that is currently active in the devcontainer. - `WarningMessage string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `EnvironmentURLs EnvironmentStatusEnvironmentURLs` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `Logs string` logs is the URL at which the environment logs can be accessed. - `Ops string` ops is the URL at which the environment ops service can be accessed. - `Ports []EnvironmentStatusEnvironmentURLsPort` - `Port int64` port is the port number of the environment port - `URL string` url is the URL at which the environment port can be accessed - `SSH EnvironmentStatusEnvironmentURLsSSH` SSH is the URL at which the environment can be accessed via SSH. - `URL string` - `SupportBundle string` support_bundle is the URL at which the environment support bundle can be accessed. - `FailureMessage []string` failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `Machine EnvironmentStatusMachine` machine contains the status of the environment machine - `FailureMessage string` failure_message contains the reason the machine failed to operate. - `Phase EnvironmentStatusMachinePhase` phase is the current phase of the environment machine - `const EnvironmentStatusMachinePhasePhaseUnspecified EnvironmentStatusMachinePhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusMachinePhasePhaseCreating EnvironmentStatusMachinePhase = "PHASE_CREATING"` - `const EnvironmentStatusMachinePhasePhaseStarting EnvironmentStatusMachinePhase = "PHASE_STARTING"` - `const EnvironmentStatusMachinePhasePhaseRunning EnvironmentStatusMachinePhase = "PHASE_RUNNING"` - `const EnvironmentStatusMachinePhasePhaseStopping EnvironmentStatusMachinePhase = "PHASE_STOPPING"` - `const EnvironmentStatusMachinePhasePhaseStopped EnvironmentStatusMachinePhase = "PHASE_STOPPED"` - `const EnvironmentStatusMachinePhasePhaseDeleting EnvironmentStatusMachinePhase = "PHASE_DELETING"` - `const EnvironmentStatusMachinePhasePhaseDeleted EnvironmentStatusMachinePhase = "PHASE_DELETED"` - `Session string` session is the session that is currently active in the machine. - `Timeout string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `Versions EnvironmentStatusMachineVersions` versions contains the versions of components in the machine. - `AmiID string` - `SupervisorCommit string` - `SupervisorVersion string` - `WarningMessage string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `Phase EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `RunnerAck EnvironmentStatusRunnerAck` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `Message string` - `SpecVersion string` - `StatusCode EnvironmentStatusRunnerAckStatusCode` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeUnspecified EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_UNSPECIFIED"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeOk EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_OK"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeInvalidResource EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_INVALID_RESOURCE"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeFailedPrecondition EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_FAILED_PRECONDITION"` - `Secrets []EnvironmentStatusSecret` secrets contains the status of the environment secrets - `ID string` id is the unique identifier of the secret. - `FailureMessage string` failure_message contains the reason the secret failed to be materialize. - `Phase EnvironmentStatusSecretsPhase` - `const EnvironmentStatusSecretsPhaseContentPhaseUnspecified EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSecretsPhaseContentPhaseCreating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseInitializing EnvironmentStatusSecretsPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSecretsPhaseContentPhaseReady EnvironmentStatusSecretsPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSecretsPhaseContentPhaseUpdating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseFailed EnvironmentStatusSecretsPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSecretsPhaseContentPhaseUnavailable EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNAVAILABLE"` - `SecretName string` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `SSHPublicKeys []EnvironmentStatusSSHPublicKey` ssh_public_keys contains the status of the environment ssh public keys - `ID string` id is the unique identifier of the public key - `Phase EnvironmentStatusSSHPublicKeysPhase` phase is the current phase of the public key - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnspecified EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseCreating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseInitializing EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseReady EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUpdating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseFailed EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnavailable EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNAVAILABLE"` - `StatusVersion string` version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `WarningMessage []string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.NewFromProject(context.TODO(), gitpod.EnvironmentNewFromProjectParams{ ProjectID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"), Spec: gitpod.F(gitpod.EnvironmentSpecParam{ Machine: gitpod.F(gitpod.EnvironmentSpecMachineParam{ Class: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }), Timeout: gitpod.F(gitpod.EnvironmentSpecTimeoutParam{ Disconnected: gitpod.F("14400s"), }), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.Environment) } ``` #### 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 `client.Environments.NewLogsToken(ctx, body) (*EnvironmentNewLogsTokenResponse, error)` **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" ``` ### Parameters - `body EnvironmentNewLogsTokenParams` - `EnvironmentID param.Field[string]` environment_id specifies the environment for which the logs token should be created. +required ### Returns - `type EnvironmentNewLogsTokenResponse struct{…}` - `AccessToken string` access_token is the token that can be used to access the logs of the environment ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.NewLogsToken(context.TODO(), gitpod.EnvironmentNewLogsTokenParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.AccessToken) } ``` #### Response ```json { "accessToken": "accessToken" } ``` ## DeleteEnvironment `client.Environments.Delete(ctx, body) (*EnvironmentDeleteResponse, error)` **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 ``` ### Parameters - `body EnvironmentDeleteParams` - `EnvironmentID param.Field[string]` environment_id specifies the environment that is going to delete. +required - `Force param.Field[bool]` 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. ### Returns - `type EnvironmentDeleteResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) environment, err := client.Environments.Delete(context.TODO(), gitpod.EnvironmentDeleteParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", environment) } ``` #### Response ```json {} ``` ## ListEnvironments `client.Environments.List(ctx, params) (*EnvironmentsPage[Environment], error)` **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"] ``` ### Parameters - `params EnvironmentListParams` - `Token param.Field[string]` Query param - `PageSize param.Field[int64]` Query param - `Filter param.Field[EnvironmentListParamsFilter]` Body param - `ArchivalStatus EnvironmentListParamsFilterArchivalStatus` archival_status filters the response based on environment archive status - `const EnvironmentListParamsFilterArchivalStatusArchivalStatusUnspecified EnvironmentListParamsFilterArchivalStatus = "ARCHIVAL_STATUS_UNSPECIFIED"` - `const EnvironmentListParamsFilterArchivalStatusArchivalStatusActive EnvironmentListParamsFilterArchivalStatus = "ARCHIVAL_STATUS_ACTIVE"` - `const EnvironmentListParamsFilterArchivalStatusArchivalStatusArchived EnvironmentListParamsFilterArchivalStatus = "ARCHIVAL_STATUS_ARCHIVED"` - `const EnvironmentListParamsFilterArchivalStatusArchivalStatusAll EnvironmentListParamsFilterArchivalStatus = "ARCHIVAL_STATUS_ALL"` - `CreatedBefore Time` created_before filters environments created before this timestamp - `CreatorIDs []string` creator_ids filters the response to only Environments created by specified members - `ProjectIDs []string` project_ids filters the response to only Environments associated with the specified projects - `Roles []EnvironmentRole` roles filters the response to only Environments with the specified roles - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` - `RunnerIDs []string` runner_ids filters the response to only Environments running on these Runner IDs - `RunnerKinds []RunnerKind` runner_kinds filters the response to only Environments running on these Runner Kinds - `const RunnerKindUnspecified RunnerKind = "RUNNER_KIND_UNSPECIFIED"` - `const RunnerKindLocal RunnerKind = "RUNNER_KIND_LOCAL"` - `const RunnerKindRemote RunnerKind = "RUNNER_KIND_REMOTE"` - `const RunnerKindLocalConfiguration RunnerKind = "RUNNER_KIND_LOCAL_CONFIGURATION"` - `SessionIDs []string` session_ids filters the response to only environments belonging to the specified sessions - `StatusPhases []EnvironmentPhase` actual_phases is a list of phases the environment must be in for it to be returned in the API call - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `Pagination param.Field[EnvironmentListParamsPagination]` Body param: pagination contains the pagination options for listing environments - `Token string` Token for the next set of results that was returned as next_token of a PaginationResponse - `PageSize int64` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `type Environment struct{…}` +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 EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `Annotations map[string, string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `ArchivedAt Time` Time when the Environment was archived. If not set, the environment is not archived. - `CreatedAt Time` Time when the Environment was created. - `Creator Subject` creator is the identity of the creator of the environment - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `LastStartedAt Time` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `LockdownAt Time` 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 string` name is the name of the environment as specified by the user - `OrganizationID string` organization_id is the ID of the organization that contains the environment - `OriginalContextURL string` original_context_url is the normalized URL from which the environment was created - `PrebuildID 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 string` If the Environment was started from a project, the project_id will reference the project. - `Role EnvironmentRole` role is the role of the environment - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` - `RunnerID string` Runner is the ID of the runner that runs this environment. - `Spec EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `Admission AdmissionLevel` admission controlls who can access the environment and its ports. - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` - `AutomationsFile EnvironmentSpecAutomationsFile` automations_file is the automations file spec of the environment - `AutomationsFilePath 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 string` - `TriggerFilter []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 bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Content EnvironmentSpecContent` content is the content spec of the environment - `GitEmail string` The Git email address - `GitUsername string` The Git username - `Initializer EnvironmentInitializer` initializer configures how the environment is to be initialized - `Specs []EnvironmentInitializerSpec` - `ContextURL EnvironmentInitializerSpecsContextURL` - `URL string` url is the URL from which the environment is created - `Git EnvironmentInitializerSpecsGit` - `CheckoutLocation string` a path relative to the environment root in which the code will be checked out to - `CloneTarget string` the value for the clone target mode - use depends on the target mode - `RemoteUri string` remote_uri is the Git remote origin - `TargetMode EnvironmentInitializerSpecsGitTargetMode` the target mode determines what gets checked out - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeUnspecified EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_UNSPECIFIED"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteHead EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_HEAD"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteCommit EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_COMMIT"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeLocalBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_LOCAL_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteTag EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_TAG"` - `UpstreamRemoteUri string` upstream_Remote_uri is the fork upstream of a repository - `Session string` - `DesiredPhase EnvironmentPhase` Phase is the desired phase of the environment - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `Devcontainer EnvironmentSpecDevcontainer` devcontainer is the devcontainer spec of the environment - `DefaultDevcontainerImage string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `DevcontainerFilePath 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 EnvironmentSpecDevcontainerDotfiles` 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 EnvironmentSpecDevcontainerLifecycleStage` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageUnspecified EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_UNSPECIFIED"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageFull EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_FULL"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStagePrebuild EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_PREBUILD"` - `Session string` - `KernelControlsConfig KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active - `Machine EnvironmentSpecMachine` machine is the machine spec of the environment - `Class string` Class denotes the class of the environment we ought to start - `Session string` - `Ports []EnvironmentSpecPort` ports is the set of ports which ought to be exposed to your network - `Admission AdmissionLevel` policy of this port - `Name string` name of this port - `Port int64` port number - `Protocol EnvironmentSpecPortsProtocol` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `const EnvironmentSpecPortsProtocolProtocolUnspecified EnvironmentSpecPortsProtocol = "PROTOCOL_UNSPECIFIED"` - `const EnvironmentSpecPortsProtocolProtocolHTTP EnvironmentSpecPortsProtocol = "PROTOCOL_HTTP"` - `const EnvironmentSpecPortsProtocolProtocolHTTPS EnvironmentSpecPortsProtocol = "PROTOCOL_HTTPS"` - `Secrets []EnvironmentSpecSecret` secrets are confidential data that is mounted into the environment - `ID string` id is the unique identifier of the secret. - `APIOnly bool` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `ContainerRegistryBasicAuthHost string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `CredentialProxy EnvironmentSpecSecretsCredentialProxy` 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 EnvironmentSpecSecretsCredentialProxyFormat` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `const EnvironmentSpecSecretsCredentialProxyFormatFormatUnspecified EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_UNSPECIFIED"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatPlain EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_PLAIN"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatBase64 EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_BASE64"` - `Header string` header is the HTTP header name to inject (e.g. "Authorization"). - `TargetHosts []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 string` - `FilePath string` file_path is the path inside the devcontainer where the secret is mounted - `GitCredentialHost string` - `Name string` name is the human readable description of the secret - `Scope EnvironmentSpecSecretsScope` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `const EnvironmentSpecSecretsScopeScopeUnspecified EnvironmentSpecSecretsScope = "SCOPE_UNSPECIFIED"` - `const EnvironmentSpecSecretsScopeScopeOrganization EnvironmentSpecSecretsScope = "SCOPE_ORGANIZATION"` - `const EnvironmentSpecSecretsScopeScopeProject EnvironmentSpecSecretsScope = "SCOPE_PROJECT"` - `const EnvironmentSpecSecretsScopeScopeUser EnvironmentSpecSecretsScope = "SCOPE_USER"` - `const EnvironmentSpecSecretsScopeScopeServiceAccount EnvironmentSpecSecretsScope = "SCOPE_SERVICE_ACCOUNT"` - `const EnvironmentSpecSecretsScopeScopeRunner EnvironmentSpecSecretsScope = "SCOPE_RUNNER"` - `Session string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `Source string` source is the source of the secret, for now control-plane or runner - `SourceRef string` source_ref into the source, in case of control-plane this is uuid of the secret - `SpecVersion 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 []EnvironmentSpecSSHPublicKey` ssh_public_keys are the public keys used to ssh into the environment - `ID string` id is the unique identifier of the public key - `Value string` value is the actual public key in the public key file format - `Timeout EnvironmentSpecTimeout` Timeout configures the environment timeout - `Disconnected 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 string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `Status EnvironmentStatus` Status is the current status of the environment - `ActivitySignal EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `Source string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `Timestamp Time` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `AutomationsFile EnvironmentStatusAutomationsFile` automations_file contains the status of the automations file. - `AutomationsFilePath string` automations_file_path is the path to the automations file relative to the repo root. - `AutomationsFilePresence EnvironmentStatusAutomationsFileAutomationsFilePresence` automations_file_presence indicates how an automations file is present in the environment. - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceUnspecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceAbsent EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_ABSENT"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceDiscovered EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceSpecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `Phase EnvironmentStatusAutomationsFilePhase` phase is the current phase of the automations file. - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnspecified EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseCreating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseInitializing EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseReady EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUpdating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseFailed EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnavailable EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the automations file session that is currently applied in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `Content EnvironmentStatusContent` content contains the status of the environment content. - `ContentLocationInMachine string` content_location_in_machine is the location of the content in the machine - `FailureMessage string` failure_message contains the reason the content initialization failed. - `Git EnvironmentStatusContentGit` 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 string` branch is branch we're currently on - `ChangedFiles []EnvironmentStatusContentGitChangedFile` changed_files is an array of changed files in the environment, possibly truncated - `ChangeType EnvironmentStatusContentGitChangedFilesChangeType` ChangeType is the type of change that happened to the file - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUnspecified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNSPECIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeAdded EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_ADDED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeModified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_MODIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeDeleted EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_DELETED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeRenamed EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_RENAMED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeCopied EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_COPIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUpdatedButUnmerged EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UPDATED_BUT_UNMERGED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUntracked EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNTRACKED"` - `OldPath string` old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `Path string` path is the path of the file - `CloneURL string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `LatestCommit string` latest_commit is the most recent commit on the current branch - `TotalChangedFiles int64` - `TotalUnpushedCommits int64` the total number of unpushed changes - `UnpushedCommits []string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `Phase EnvironmentStatusContentPhase` phase is the current phase of the environment content - `const EnvironmentStatusContentPhaseContentPhaseUnspecified EnvironmentStatusContentPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusContentPhaseContentPhaseCreating EnvironmentStatusContentPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusContentPhaseContentPhaseInitializing EnvironmentStatusContentPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusContentPhaseContentPhaseReady EnvironmentStatusContentPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusContentPhaseContentPhaseUpdating EnvironmentStatusContentPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusContentPhaseContentPhaseFailed EnvironmentStatusContentPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusContentPhaseContentPhaseUnavailable EnvironmentStatusContentPhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `Devcontainer EnvironmentStatusDevcontainer` devcontainer contains the status of the devcontainer. - `ContainerID string` container_id is the ID of the container. - `ContainerName string` container_name is the name of the container that is used to connect to the devcontainer - `DevcontainerconfigInSync bool` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `DevcontainerFilePath string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `DevcontainerFilePresence EnvironmentStatusDevcontainerDevcontainerFilePresence` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceUnspecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceGenerated EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_GENERATED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceDiscovered EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceSpecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the devcontainer failed to operate. - `Phase EnvironmentStatusDevcontainerPhase` phase is the current phase of the devcontainer - `const EnvironmentStatusDevcontainerPhasePhaseUnspecified EnvironmentStatusDevcontainerPhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerPhasePhaseCreating EnvironmentStatusDevcontainerPhase = "PHASE_CREATING"` - `const EnvironmentStatusDevcontainerPhasePhaseRunning EnvironmentStatusDevcontainerPhase = "PHASE_RUNNING"` - `const EnvironmentStatusDevcontainerPhasePhaseStopped EnvironmentStatusDevcontainerPhase = "PHASE_STOPPED"` - `const EnvironmentStatusDevcontainerPhasePhaseFailed EnvironmentStatusDevcontainerPhase = "PHASE_FAILED"` - `RemoteUser string` remote_user is the user that is used to connect to the devcontainer - `RemoteWorkspaceFolder string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `SecretsInSync bool` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `Session string` session is the session that is currently active in the devcontainer. - `WarningMessage string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `EnvironmentURLs EnvironmentStatusEnvironmentURLs` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `Logs string` logs is the URL at which the environment logs can be accessed. - `Ops string` ops is the URL at which the environment ops service can be accessed. - `Ports []EnvironmentStatusEnvironmentURLsPort` - `Port int64` port is the port number of the environment port - `URL string` url is the URL at which the environment port can be accessed - `SSH EnvironmentStatusEnvironmentURLsSSH` SSH is the URL at which the environment can be accessed via SSH. - `URL string` - `SupportBundle string` support_bundle is the URL at which the environment support bundle can be accessed. - `FailureMessage []string` failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `Machine EnvironmentStatusMachine` machine contains the status of the environment machine - `FailureMessage string` failure_message contains the reason the machine failed to operate. - `Phase EnvironmentStatusMachinePhase` phase is the current phase of the environment machine - `const EnvironmentStatusMachinePhasePhaseUnspecified EnvironmentStatusMachinePhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusMachinePhasePhaseCreating EnvironmentStatusMachinePhase = "PHASE_CREATING"` - `const EnvironmentStatusMachinePhasePhaseStarting EnvironmentStatusMachinePhase = "PHASE_STARTING"` - `const EnvironmentStatusMachinePhasePhaseRunning EnvironmentStatusMachinePhase = "PHASE_RUNNING"` - `const EnvironmentStatusMachinePhasePhaseStopping EnvironmentStatusMachinePhase = "PHASE_STOPPING"` - `const EnvironmentStatusMachinePhasePhaseStopped EnvironmentStatusMachinePhase = "PHASE_STOPPED"` - `const EnvironmentStatusMachinePhasePhaseDeleting EnvironmentStatusMachinePhase = "PHASE_DELETING"` - `const EnvironmentStatusMachinePhasePhaseDeleted EnvironmentStatusMachinePhase = "PHASE_DELETED"` - `Session string` session is the session that is currently active in the machine. - `Timeout string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `Versions EnvironmentStatusMachineVersions` versions contains the versions of components in the machine. - `AmiID string` - `SupervisorCommit string` - `SupervisorVersion string` - `WarningMessage string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `Phase EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `RunnerAck EnvironmentStatusRunnerAck` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `Message string` - `SpecVersion string` - `StatusCode EnvironmentStatusRunnerAckStatusCode` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeUnspecified EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_UNSPECIFIED"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeOk EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_OK"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeInvalidResource EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_INVALID_RESOURCE"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeFailedPrecondition EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_FAILED_PRECONDITION"` - `Secrets []EnvironmentStatusSecret` secrets contains the status of the environment secrets - `ID string` id is the unique identifier of the secret. - `FailureMessage string` failure_message contains the reason the secret failed to be materialize. - `Phase EnvironmentStatusSecretsPhase` - `const EnvironmentStatusSecretsPhaseContentPhaseUnspecified EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSecretsPhaseContentPhaseCreating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseInitializing EnvironmentStatusSecretsPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSecretsPhaseContentPhaseReady EnvironmentStatusSecretsPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSecretsPhaseContentPhaseUpdating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseFailed EnvironmentStatusSecretsPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSecretsPhaseContentPhaseUnavailable EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNAVAILABLE"` - `SecretName string` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `SSHPublicKeys []EnvironmentStatusSSHPublicKey` ssh_public_keys contains the status of the environment ssh public keys - `ID string` id is the unique identifier of the public key - `Phase EnvironmentStatusSSHPublicKeysPhase` phase is the current phase of the public key - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnspecified EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseCreating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseInitializing EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseReady EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUpdating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseFailed EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnavailable EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNAVAILABLE"` - `StatusVersion string` version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `WarningMessage []string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) page, err := client.Environments.List(context.TODO(), gitpod.EnvironmentListParams{ Filter: gitpod.F(gitpod.EnvironmentListParamsFilter{ CreatorIDs: gitpod.F([]string{"f53d2330-3795-4c5d-a1f3-453121af9c60"}), RunnerIDs: gitpod.F([]string{"e6aa9c54-89d3-42c1-ac31-bd8d8f1concentrate"}), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 `client.Environments.MarkActive(ctx, body) (*EnvironmentMarkActiveResponse, error)` **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" ``` ### Parameters - `body EnvironmentMarkActiveParams` - `ActivitySignal param.Field[EnvironmentActivitySignal]` activity_signal specifies the activity. - `EnvironmentID param.Field[string]` The ID of the environment to update activity for. ### Returns - `type EnvironmentMarkActiveResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "time" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.MarkActive(context.TODO(), gitpod.EnvironmentMarkActiveParams{ ActivitySignal: gitpod.F(gitpod.EnvironmentActivitySignalParam{ Source: gitpod.F("VS Code"), Timestamp: gitpod.F(time.Now()), }), EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` ## GetEnvironment `client.Environments.Get(ctx, body) (*EnvironmentGetResponse, error)` **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" ``` ### Parameters - `body EnvironmentGetParams` - `EnvironmentID param.Field[string]` environment_id specifies the environment to get ### Returns - `type EnvironmentGetResponse struct{…}` - `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 EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `Annotations map[string, string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `ArchivedAt Time` Time when the Environment was archived. If not set, the environment is not archived. - `CreatedAt Time` Time when the Environment was created. - `Creator Subject` creator is the identity of the creator of the environment - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `LastStartedAt Time` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `LockdownAt Time` 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 string` name is the name of the environment as specified by the user - `OrganizationID string` organization_id is the ID of the organization that contains the environment - `OriginalContextURL string` original_context_url is the normalized URL from which the environment was created - `PrebuildID 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 string` If the Environment was started from a project, the project_id will reference the project. - `Role EnvironmentRole` role is the role of the environment - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` - `RunnerID string` Runner is the ID of the runner that runs this environment. - `Spec EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `Admission AdmissionLevel` admission controlls who can access the environment and its ports. - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` - `AutomationsFile EnvironmentSpecAutomationsFile` automations_file is the automations file spec of the environment - `AutomationsFilePath 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 string` - `TriggerFilter []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 bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Content EnvironmentSpecContent` content is the content spec of the environment - `GitEmail string` The Git email address - `GitUsername string` The Git username - `Initializer EnvironmentInitializer` initializer configures how the environment is to be initialized - `Specs []EnvironmentInitializerSpec` - `ContextURL EnvironmentInitializerSpecsContextURL` - `URL string` url is the URL from which the environment is created - `Git EnvironmentInitializerSpecsGit` - `CheckoutLocation string` a path relative to the environment root in which the code will be checked out to - `CloneTarget string` the value for the clone target mode - use depends on the target mode - `RemoteUri string` remote_uri is the Git remote origin - `TargetMode EnvironmentInitializerSpecsGitTargetMode` the target mode determines what gets checked out - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeUnspecified EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_UNSPECIFIED"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteHead EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_HEAD"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteCommit EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_COMMIT"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeLocalBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_LOCAL_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteTag EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_TAG"` - `UpstreamRemoteUri string` upstream_Remote_uri is the fork upstream of a repository - `Session string` - `DesiredPhase EnvironmentPhase` Phase is the desired phase of the environment - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `Devcontainer EnvironmentSpecDevcontainer` devcontainer is the devcontainer spec of the environment - `DefaultDevcontainerImage string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `DevcontainerFilePath 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 EnvironmentSpecDevcontainerDotfiles` 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 EnvironmentSpecDevcontainerLifecycleStage` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageUnspecified EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_UNSPECIFIED"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageFull EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_FULL"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStagePrebuild EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_PREBUILD"` - `Session string` - `KernelControlsConfig KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active - `Machine EnvironmentSpecMachine` machine is the machine spec of the environment - `Class string` Class denotes the class of the environment we ought to start - `Session string` - `Ports []EnvironmentSpecPort` ports is the set of ports which ought to be exposed to your network - `Admission AdmissionLevel` policy of this port - `Name string` name of this port - `Port int64` port number - `Protocol EnvironmentSpecPortsProtocol` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `const EnvironmentSpecPortsProtocolProtocolUnspecified EnvironmentSpecPortsProtocol = "PROTOCOL_UNSPECIFIED"` - `const EnvironmentSpecPortsProtocolProtocolHTTP EnvironmentSpecPortsProtocol = "PROTOCOL_HTTP"` - `const EnvironmentSpecPortsProtocolProtocolHTTPS EnvironmentSpecPortsProtocol = "PROTOCOL_HTTPS"` - `Secrets []EnvironmentSpecSecret` secrets are confidential data that is mounted into the environment - `ID string` id is the unique identifier of the secret. - `APIOnly bool` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `ContainerRegistryBasicAuthHost string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `CredentialProxy EnvironmentSpecSecretsCredentialProxy` 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 EnvironmentSpecSecretsCredentialProxyFormat` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `const EnvironmentSpecSecretsCredentialProxyFormatFormatUnspecified EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_UNSPECIFIED"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatPlain EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_PLAIN"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatBase64 EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_BASE64"` - `Header string` header is the HTTP header name to inject (e.g. "Authorization"). - `TargetHosts []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 string` - `FilePath string` file_path is the path inside the devcontainer where the secret is mounted - `GitCredentialHost string` - `Name string` name is the human readable description of the secret - `Scope EnvironmentSpecSecretsScope` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `const EnvironmentSpecSecretsScopeScopeUnspecified EnvironmentSpecSecretsScope = "SCOPE_UNSPECIFIED"` - `const EnvironmentSpecSecretsScopeScopeOrganization EnvironmentSpecSecretsScope = "SCOPE_ORGANIZATION"` - `const EnvironmentSpecSecretsScopeScopeProject EnvironmentSpecSecretsScope = "SCOPE_PROJECT"` - `const EnvironmentSpecSecretsScopeScopeUser EnvironmentSpecSecretsScope = "SCOPE_USER"` - `const EnvironmentSpecSecretsScopeScopeServiceAccount EnvironmentSpecSecretsScope = "SCOPE_SERVICE_ACCOUNT"` - `const EnvironmentSpecSecretsScopeScopeRunner EnvironmentSpecSecretsScope = "SCOPE_RUNNER"` - `Session string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `Source string` source is the source of the secret, for now control-plane or runner - `SourceRef string` source_ref into the source, in case of control-plane this is uuid of the secret - `SpecVersion 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 []EnvironmentSpecSSHPublicKey` ssh_public_keys are the public keys used to ssh into the environment - `ID string` id is the unique identifier of the public key - `Value string` value is the actual public key in the public key file format - `Timeout EnvironmentSpecTimeout` Timeout configures the environment timeout - `Disconnected 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 string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `Status EnvironmentStatus` Status is the current status of the environment - `ActivitySignal EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `Source string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `Timestamp Time` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `AutomationsFile EnvironmentStatusAutomationsFile` automations_file contains the status of the automations file. - `AutomationsFilePath string` automations_file_path is the path to the automations file relative to the repo root. - `AutomationsFilePresence EnvironmentStatusAutomationsFileAutomationsFilePresence` automations_file_presence indicates how an automations file is present in the environment. - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceUnspecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceAbsent EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_ABSENT"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceDiscovered EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceSpecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `Phase EnvironmentStatusAutomationsFilePhase` phase is the current phase of the automations file. - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnspecified EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseCreating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseInitializing EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseReady EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUpdating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseFailed EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnavailable EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the automations file session that is currently applied in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `Content EnvironmentStatusContent` content contains the status of the environment content. - `ContentLocationInMachine string` content_location_in_machine is the location of the content in the machine - `FailureMessage string` failure_message contains the reason the content initialization failed. - `Git EnvironmentStatusContentGit` 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 string` branch is branch we're currently on - `ChangedFiles []EnvironmentStatusContentGitChangedFile` changed_files is an array of changed files in the environment, possibly truncated - `ChangeType EnvironmentStatusContentGitChangedFilesChangeType` ChangeType is the type of change that happened to the file - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUnspecified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNSPECIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeAdded EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_ADDED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeModified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_MODIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeDeleted EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_DELETED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeRenamed EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_RENAMED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeCopied EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_COPIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUpdatedButUnmerged EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UPDATED_BUT_UNMERGED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUntracked EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNTRACKED"` - `OldPath string` old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `Path string` path is the path of the file - `CloneURL string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `LatestCommit string` latest_commit is the most recent commit on the current branch - `TotalChangedFiles int64` - `TotalUnpushedCommits int64` the total number of unpushed changes - `UnpushedCommits []string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `Phase EnvironmentStatusContentPhase` phase is the current phase of the environment content - `const EnvironmentStatusContentPhaseContentPhaseUnspecified EnvironmentStatusContentPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusContentPhaseContentPhaseCreating EnvironmentStatusContentPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusContentPhaseContentPhaseInitializing EnvironmentStatusContentPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusContentPhaseContentPhaseReady EnvironmentStatusContentPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusContentPhaseContentPhaseUpdating EnvironmentStatusContentPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusContentPhaseContentPhaseFailed EnvironmentStatusContentPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusContentPhaseContentPhaseUnavailable EnvironmentStatusContentPhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `Devcontainer EnvironmentStatusDevcontainer` devcontainer contains the status of the devcontainer. - `ContainerID string` container_id is the ID of the container. - `ContainerName string` container_name is the name of the container that is used to connect to the devcontainer - `DevcontainerconfigInSync bool` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `DevcontainerFilePath string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `DevcontainerFilePresence EnvironmentStatusDevcontainerDevcontainerFilePresence` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceUnspecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceGenerated EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_GENERATED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceDiscovered EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceSpecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the devcontainer failed to operate. - `Phase EnvironmentStatusDevcontainerPhase` phase is the current phase of the devcontainer - `const EnvironmentStatusDevcontainerPhasePhaseUnspecified EnvironmentStatusDevcontainerPhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerPhasePhaseCreating EnvironmentStatusDevcontainerPhase = "PHASE_CREATING"` - `const EnvironmentStatusDevcontainerPhasePhaseRunning EnvironmentStatusDevcontainerPhase = "PHASE_RUNNING"` - `const EnvironmentStatusDevcontainerPhasePhaseStopped EnvironmentStatusDevcontainerPhase = "PHASE_STOPPED"` - `const EnvironmentStatusDevcontainerPhasePhaseFailed EnvironmentStatusDevcontainerPhase = "PHASE_FAILED"` - `RemoteUser string` remote_user is the user that is used to connect to the devcontainer - `RemoteWorkspaceFolder string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `SecretsInSync bool` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `Session string` session is the session that is currently active in the devcontainer. - `WarningMessage string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `EnvironmentURLs EnvironmentStatusEnvironmentURLs` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `Logs string` logs is the URL at which the environment logs can be accessed. - `Ops string` ops is the URL at which the environment ops service can be accessed. - `Ports []EnvironmentStatusEnvironmentURLsPort` - `Port int64` port is the port number of the environment port - `URL string` url is the URL at which the environment port can be accessed - `SSH EnvironmentStatusEnvironmentURLsSSH` SSH is the URL at which the environment can be accessed via SSH. - `URL string` - `SupportBundle string` support_bundle is the URL at which the environment support bundle can be accessed. - `FailureMessage []string` failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `Machine EnvironmentStatusMachine` machine contains the status of the environment machine - `FailureMessage string` failure_message contains the reason the machine failed to operate. - `Phase EnvironmentStatusMachinePhase` phase is the current phase of the environment machine - `const EnvironmentStatusMachinePhasePhaseUnspecified EnvironmentStatusMachinePhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusMachinePhasePhaseCreating EnvironmentStatusMachinePhase = "PHASE_CREATING"` - `const EnvironmentStatusMachinePhasePhaseStarting EnvironmentStatusMachinePhase = "PHASE_STARTING"` - `const EnvironmentStatusMachinePhasePhaseRunning EnvironmentStatusMachinePhase = "PHASE_RUNNING"` - `const EnvironmentStatusMachinePhasePhaseStopping EnvironmentStatusMachinePhase = "PHASE_STOPPING"` - `const EnvironmentStatusMachinePhasePhaseStopped EnvironmentStatusMachinePhase = "PHASE_STOPPED"` - `const EnvironmentStatusMachinePhasePhaseDeleting EnvironmentStatusMachinePhase = "PHASE_DELETING"` - `const EnvironmentStatusMachinePhasePhaseDeleted EnvironmentStatusMachinePhase = "PHASE_DELETED"` - `Session string` session is the session that is currently active in the machine. - `Timeout string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `Versions EnvironmentStatusMachineVersions` versions contains the versions of components in the machine. - `AmiID string` - `SupervisorCommit string` - `SupervisorVersion string` - `WarningMessage string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `Phase EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `RunnerAck EnvironmentStatusRunnerAck` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `Message string` - `SpecVersion string` - `StatusCode EnvironmentStatusRunnerAckStatusCode` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeUnspecified EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_UNSPECIFIED"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeOk EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_OK"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeInvalidResource EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_INVALID_RESOURCE"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeFailedPrecondition EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_FAILED_PRECONDITION"` - `Secrets []EnvironmentStatusSecret` secrets contains the status of the environment secrets - `ID string` id is the unique identifier of the secret. - `FailureMessage string` failure_message contains the reason the secret failed to be materialize. - `Phase EnvironmentStatusSecretsPhase` - `const EnvironmentStatusSecretsPhaseContentPhaseUnspecified EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSecretsPhaseContentPhaseCreating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseInitializing EnvironmentStatusSecretsPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSecretsPhaseContentPhaseReady EnvironmentStatusSecretsPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSecretsPhaseContentPhaseUpdating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseFailed EnvironmentStatusSecretsPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSecretsPhaseContentPhaseUnavailable EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNAVAILABLE"` - `SecretName string` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `SSHPublicKeys []EnvironmentStatusSSHPublicKey` ssh_public_keys contains the status of the environment ssh public keys - `ID string` id is the unique identifier of the public key - `Phase EnvironmentStatusSSHPublicKeysPhase` phase is the current phase of the public key - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnspecified EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseCreating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseInitializing EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseReady EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUpdating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseFailed EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnavailable EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNAVAILABLE"` - `StatusVersion string` version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `WarningMessage []string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) environment, err := client.Environments.Get(context.TODO(), gitpod.EnvironmentGetParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", environment.Environment) } ``` #### 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 `client.Environments.Start(ctx, body) (*EnvironmentStartResponse, error)` **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" ``` ### Parameters - `body EnvironmentStartParams` - `EnvironmentID param.Field[string]` environment_id specifies which environment should be started. ### Returns - `type EnvironmentStartResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Start(context.TODO(), gitpod.EnvironmentStartParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` ## StopEnvironment `client.Environments.Stop(ctx, body) (*EnvironmentStopResponse, error)` **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" ``` ### Parameters - `body EnvironmentStopParams` - `EnvironmentID param.Field[string]` environment_id specifies which environment should be stopped. +required ### Returns - `type EnvironmentStopResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Stop(context.TODO(), gitpod.EnvironmentStopParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` ## UnarchiveEnvironment `client.Environments.Unarchive(ctx, body) (*EnvironmentUnarchiveResponse, error)` **post** `/gitpod.v1.EnvironmentService/UnarchiveEnvironment` Unarchives an environment. ### Examples - Unarchive an environment: ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" ``` ### Parameters - `body EnvironmentUnarchiveParams` - `EnvironmentID param.Field[string]` environment_id specifies the environment to unarchive. +required ### Returns - `type EnvironmentUnarchiveResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Unarchive(context.TODO(), gitpod.EnvironmentUnarchiveParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` ## UpdateEnvironment `client.Environments.Update(ctx, body) (*EnvironmentUpdateResponse, error)` **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. ### Parameters - `body EnvironmentUpdateParams` - `EnvironmentID param.Field[string]` environment_id specifies which environment should be updated. +required - `Metadata param.Field[EnvironmentUpdateParamsMetadata]` - `Name string` name is the user-defined display name of the environment - `Spec param.Field[EnvironmentUpdateParamsSpec]` - `AutomationsFile EnvironmentUpdateParamsSpecAutomationsFile` automations_file is the automations file spec of the environment - `AutomationsFilePath 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 string` - `Content EnvironmentUpdateParamsSpecContent` - `GitEmail string` The Git email address - `GitUsername string` The Git username - `Initializer EnvironmentInitializer` initializer configures how the environment is to be initialized - `Specs []EnvironmentInitializerSpec` - `ContextURL EnvironmentInitializerSpecsContextURL` - `URL string` url is the URL from which the environment is created - `Git EnvironmentInitializerSpecsGit` - `CheckoutLocation string` a path relative to the environment root in which the code will be checked out to - `CloneTarget string` the value for the clone target mode - use depends on the target mode - `RemoteUri string` remote_uri is the Git remote origin - `TargetMode EnvironmentInitializerSpecsGitTargetMode` the target mode determines what gets checked out - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeUnspecified EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_UNSPECIFIED"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteHead EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_HEAD"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteCommit EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_COMMIT"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeLocalBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_LOCAL_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteTag EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_TAG"` - `UpstreamRemoteUri string` upstream_Remote_uri is the fork upstream of a repository - `Session string` session should be changed to trigger a content reinitialization - `Devcontainer EnvironmentUpdateParamsSpecDevcontainer` - `DevcontainerFilePath 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 string` session should be changed to trigger a devcontainer rebuild - `KernelControlsConfig KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active - `Ports []EnvironmentUpdateParamsSpecPort` ports controls port sharing - `Admission AdmissionLevel` policy of this port - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` - `Name string` name of this port - `Port int64` port number - `Protocol EnvironmentUpdateParamsSpecPortsProtocol` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `const EnvironmentUpdateParamsSpecPortsProtocolProtocolUnspecified EnvironmentUpdateParamsSpecPortsProtocol = "PROTOCOL_UNSPECIFIED"` - `const EnvironmentUpdateParamsSpecPortsProtocolProtocolHTTP EnvironmentUpdateParamsSpecPortsProtocol = "PROTOCOL_HTTP"` - `const EnvironmentUpdateParamsSpecPortsProtocolProtocolHTTPS EnvironmentUpdateParamsSpecPortsProtocol = "PROTOCOL_HTTPS"` - `SSHPublicKeys []EnvironmentUpdateParamsSpecSSHPublicKey` ssh_public_keys are the public keys to update empty array means nothing to update - `ID string` id is the unique identifier of the public key - `Value string` value is the actual public key in the public key file format if not provided, the public key will be removed - `Timeout EnvironmentUpdateParamsSpecTimeout` Timeout configures the environment timeout - `Disconnected 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') ``` ### Returns - `type EnvironmentUpdateResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) environment, err := client.Environments.Update(context.TODO(), gitpod.EnvironmentUpdateParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), Spec: gitpod.F(gitpod.EnvironmentUpdateParamsSpec{ SSHPublicKeys: gitpod.F([]gitpod.EnvironmentUpdateParamsSpecSSHPublicKey{gitpod.EnvironmentUpdateParamsSpecSSHPublicKey{ ID: gitpod.F("0194b7c1-c954-718d-91a4-9a742aa5fc11"), Value: gitpod.F("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."), }}), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", environment) } ``` #### Response ```json {} ``` ## Domain Types ### Admission Level - `type AdmissionLevel string` Admission level describes who can access an environment instance and its ports. - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` ### Bpf Debug Level - `type BpfDebugLevel string` BPFDebugLevel controls the verbosity of BPF trace_pipe output (bpf_printk). Applies to all BPF-based agents (veto exec, future agents). - `const BpfDebugLevelUnspecified BpfDebugLevel = "BPF_DEBUG_LEVEL_UNSPECIFIED"` - `const BpfDebugLevelInfo BpfDebugLevel = "BPF_DEBUG_LEVEL_INFO"` - `const BpfDebugLevelVerbose BpfDebugLevel = "BPF_DEBUG_LEVEL_VERBOSE"` ### Environment - `type Environment struct{…}` +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 EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `Annotations map[string, string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `ArchivedAt Time` Time when the Environment was archived. If not set, the environment is not archived. - `CreatedAt Time` Time when the Environment was created. - `Creator Subject` creator is the identity of the creator of the environment - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `LastStartedAt Time` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `LockdownAt Time` 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 string` name is the name of the environment as specified by the user - `OrganizationID string` organization_id is the ID of the organization that contains the environment - `OriginalContextURL string` original_context_url is the normalized URL from which the environment was created - `PrebuildID 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 string` If the Environment was started from a project, the project_id will reference the project. - `Role EnvironmentRole` role is the role of the environment - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` - `RunnerID string` Runner is the ID of the runner that runs this environment. - `Spec EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `Admission AdmissionLevel` admission controlls who can access the environment and its ports. - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` - `AutomationsFile EnvironmentSpecAutomationsFile` automations_file is the automations file spec of the environment - `AutomationsFilePath 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 string` - `TriggerFilter []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 bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Content EnvironmentSpecContent` content is the content spec of the environment - `GitEmail string` The Git email address - `GitUsername string` The Git username - `Initializer EnvironmentInitializer` initializer configures how the environment is to be initialized - `Specs []EnvironmentInitializerSpec` - `ContextURL EnvironmentInitializerSpecsContextURL` - `URL string` url is the URL from which the environment is created - `Git EnvironmentInitializerSpecsGit` - `CheckoutLocation string` a path relative to the environment root in which the code will be checked out to - `CloneTarget string` the value for the clone target mode - use depends on the target mode - `RemoteUri string` remote_uri is the Git remote origin - `TargetMode EnvironmentInitializerSpecsGitTargetMode` the target mode determines what gets checked out - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeUnspecified EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_UNSPECIFIED"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteHead EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_HEAD"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteCommit EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_COMMIT"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeLocalBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_LOCAL_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteTag EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_TAG"` - `UpstreamRemoteUri string` upstream_Remote_uri is the fork upstream of a repository - `Session string` - `DesiredPhase EnvironmentPhase` Phase is the desired phase of the environment - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `Devcontainer EnvironmentSpecDevcontainer` devcontainer is the devcontainer spec of the environment - `DefaultDevcontainerImage string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `DevcontainerFilePath 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 EnvironmentSpecDevcontainerDotfiles` 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 EnvironmentSpecDevcontainerLifecycleStage` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageUnspecified EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_UNSPECIFIED"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageFull EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_FULL"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStagePrebuild EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_PREBUILD"` - `Session string` - `KernelControlsConfig KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active - `Machine EnvironmentSpecMachine` machine is the machine spec of the environment - `Class string` Class denotes the class of the environment we ought to start - `Session string` - `Ports []EnvironmentSpecPort` ports is the set of ports which ought to be exposed to your network - `Admission AdmissionLevel` policy of this port - `Name string` name of this port - `Port int64` port number - `Protocol EnvironmentSpecPortsProtocol` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `const EnvironmentSpecPortsProtocolProtocolUnspecified EnvironmentSpecPortsProtocol = "PROTOCOL_UNSPECIFIED"` - `const EnvironmentSpecPortsProtocolProtocolHTTP EnvironmentSpecPortsProtocol = "PROTOCOL_HTTP"` - `const EnvironmentSpecPortsProtocolProtocolHTTPS EnvironmentSpecPortsProtocol = "PROTOCOL_HTTPS"` - `Secrets []EnvironmentSpecSecret` secrets are confidential data that is mounted into the environment - `ID string` id is the unique identifier of the secret. - `APIOnly bool` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `ContainerRegistryBasicAuthHost string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `CredentialProxy EnvironmentSpecSecretsCredentialProxy` 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 EnvironmentSpecSecretsCredentialProxyFormat` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `const EnvironmentSpecSecretsCredentialProxyFormatFormatUnspecified EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_UNSPECIFIED"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatPlain EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_PLAIN"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatBase64 EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_BASE64"` - `Header string` header is the HTTP header name to inject (e.g. "Authorization"). - `TargetHosts []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 string` - `FilePath string` file_path is the path inside the devcontainer where the secret is mounted - `GitCredentialHost string` - `Name string` name is the human readable description of the secret - `Scope EnvironmentSpecSecretsScope` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `const EnvironmentSpecSecretsScopeScopeUnspecified EnvironmentSpecSecretsScope = "SCOPE_UNSPECIFIED"` - `const EnvironmentSpecSecretsScopeScopeOrganization EnvironmentSpecSecretsScope = "SCOPE_ORGANIZATION"` - `const EnvironmentSpecSecretsScopeScopeProject EnvironmentSpecSecretsScope = "SCOPE_PROJECT"` - `const EnvironmentSpecSecretsScopeScopeUser EnvironmentSpecSecretsScope = "SCOPE_USER"` - `const EnvironmentSpecSecretsScopeScopeServiceAccount EnvironmentSpecSecretsScope = "SCOPE_SERVICE_ACCOUNT"` - `const EnvironmentSpecSecretsScopeScopeRunner EnvironmentSpecSecretsScope = "SCOPE_RUNNER"` - `Session string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `Source string` source is the source of the secret, for now control-plane or runner - `SourceRef string` source_ref into the source, in case of control-plane this is uuid of the secret - `SpecVersion 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 []EnvironmentSpecSSHPublicKey` ssh_public_keys are the public keys used to ssh into the environment - `ID string` id is the unique identifier of the public key - `Value string` value is the actual public key in the public key file format - `Timeout EnvironmentSpecTimeout` Timeout configures the environment timeout - `Disconnected 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 string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `Status EnvironmentStatus` Status is the current status of the environment - `ActivitySignal EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `Source string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `Timestamp Time` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `AutomationsFile EnvironmentStatusAutomationsFile` automations_file contains the status of the automations file. - `AutomationsFilePath string` automations_file_path is the path to the automations file relative to the repo root. - `AutomationsFilePresence EnvironmentStatusAutomationsFileAutomationsFilePresence` automations_file_presence indicates how an automations file is present in the environment. - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceUnspecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceAbsent EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_ABSENT"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceDiscovered EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceSpecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `Phase EnvironmentStatusAutomationsFilePhase` phase is the current phase of the automations file. - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnspecified EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseCreating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseInitializing EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseReady EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUpdating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseFailed EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnavailable EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the automations file session that is currently applied in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `Content EnvironmentStatusContent` content contains the status of the environment content. - `ContentLocationInMachine string` content_location_in_machine is the location of the content in the machine - `FailureMessage string` failure_message contains the reason the content initialization failed. - `Git EnvironmentStatusContentGit` 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 string` branch is branch we're currently on - `ChangedFiles []EnvironmentStatusContentGitChangedFile` changed_files is an array of changed files in the environment, possibly truncated - `ChangeType EnvironmentStatusContentGitChangedFilesChangeType` ChangeType is the type of change that happened to the file - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUnspecified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNSPECIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeAdded EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_ADDED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeModified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_MODIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeDeleted EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_DELETED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeRenamed EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_RENAMED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeCopied EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_COPIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUpdatedButUnmerged EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UPDATED_BUT_UNMERGED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUntracked EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNTRACKED"` - `OldPath string` old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `Path string` path is the path of the file - `CloneURL string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `LatestCommit string` latest_commit is the most recent commit on the current branch - `TotalChangedFiles int64` - `TotalUnpushedCommits int64` the total number of unpushed changes - `UnpushedCommits []string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `Phase EnvironmentStatusContentPhase` phase is the current phase of the environment content - `const EnvironmentStatusContentPhaseContentPhaseUnspecified EnvironmentStatusContentPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusContentPhaseContentPhaseCreating EnvironmentStatusContentPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusContentPhaseContentPhaseInitializing EnvironmentStatusContentPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusContentPhaseContentPhaseReady EnvironmentStatusContentPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusContentPhaseContentPhaseUpdating EnvironmentStatusContentPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusContentPhaseContentPhaseFailed EnvironmentStatusContentPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusContentPhaseContentPhaseUnavailable EnvironmentStatusContentPhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `Devcontainer EnvironmentStatusDevcontainer` devcontainer contains the status of the devcontainer. - `ContainerID string` container_id is the ID of the container. - `ContainerName string` container_name is the name of the container that is used to connect to the devcontainer - `DevcontainerconfigInSync bool` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `DevcontainerFilePath string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `DevcontainerFilePresence EnvironmentStatusDevcontainerDevcontainerFilePresence` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceUnspecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceGenerated EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_GENERATED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceDiscovered EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceSpecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the devcontainer failed to operate. - `Phase EnvironmentStatusDevcontainerPhase` phase is the current phase of the devcontainer - `const EnvironmentStatusDevcontainerPhasePhaseUnspecified EnvironmentStatusDevcontainerPhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerPhasePhaseCreating EnvironmentStatusDevcontainerPhase = "PHASE_CREATING"` - `const EnvironmentStatusDevcontainerPhasePhaseRunning EnvironmentStatusDevcontainerPhase = "PHASE_RUNNING"` - `const EnvironmentStatusDevcontainerPhasePhaseStopped EnvironmentStatusDevcontainerPhase = "PHASE_STOPPED"` - `const EnvironmentStatusDevcontainerPhasePhaseFailed EnvironmentStatusDevcontainerPhase = "PHASE_FAILED"` - `RemoteUser string` remote_user is the user that is used to connect to the devcontainer - `RemoteWorkspaceFolder string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `SecretsInSync bool` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `Session string` session is the session that is currently active in the devcontainer. - `WarningMessage string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `EnvironmentURLs EnvironmentStatusEnvironmentURLs` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `Logs string` logs is the URL at which the environment logs can be accessed. - `Ops string` ops is the URL at which the environment ops service can be accessed. - `Ports []EnvironmentStatusEnvironmentURLsPort` - `Port int64` port is the port number of the environment port - `URL string` url is the URL at which the environment port can be accessed - `SSH EnvironmentStatusEnvironmentURLsSSH` SSH is the URL at which the environment can be accessed via SSH. - `URL string` - `SupportBundle string` support_bundle is the URL at which the environment support bundle can be accessed. - `FailureMessage []string` failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `Machine EnvironmentStatusMachine` machine contains the status of the environment machine - `FailureMessage string` failure_message contains the reason the machine failed to operate. - `Phase EnvironmentStatusMachinePhase` phase is the current phase of the environment machine - `const EnvironmentStatusMachinePhasePhaseUnspecified EnvironmentStatusMachinePhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusMachinePhasePhaseCreating EnvironmentStatusMachinePhase = "PHASE_CREATING"` - `const EnvironmentStatusMachinePhasePhaseStarting EnvironmentStatusMachinePhase = "PHASE_STARTING"` - `const EnvironmentStatusMachinePhasePhaseRunning EnvironmentStatusMachinePhase = "PHASE_RUNNING"` - `const EnvironmentStatusMachinePhasePhaseStopping EnvironmentStatusMachinePhase = "PHASE_STOPPING"` - `const EnvironmentStatusMachinePhasePhaseStopped EnvironmentStatusMachinePhase = "PHASE_STOPPED"` - `const EnvironmentStatusMachinePhasePhaseDeleting EnvironmentStatusMachinePhase = "PHASE_DELETING"` - `const EnvironmentStatusMachinePhasePhaseDeleted EnvironmentStatusMachinePhase = "PHASE_DELETED"` - `Session string` session is the session that is currently active in the machine. - `Timeout string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `Versions EnvironmentStatusMachineVersions` versions contains the versions of components in the machine. - `AmiID string` - `SupervisorCommit string` - `SupervisorVersion string` - `WarningMessage string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `Phase EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `RunnerAck EnvironmentStatusRunnerAck` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `Message string` - `SpecVersion string` - `StatusCode EnvironmentStatusRunnerAckStatusCode` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeUnspecified EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_UNSPECIFIED"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeOk EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_OK"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeInvalidResource EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_INVALID_RESOURCE"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeFailedPrecondition EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_FAILED_PRECONDITION"` - `Secrets []EnvironmentStatusSecret` secrets contains the status of the environment secrets - `ID string` id is the unique identifier of the secret. - `FailureMessage string` failure_message contains the reason the secret failed to be materialize. - `Phase EnvironmentStatusSecretsPhase` - `const EnvironmentStatusSecretsPhaseContentPhaseUnspecified EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSecretsPhaseContentPhaseCreating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseInitializing EnvironmentStatusSecretsPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSecretsPhaseContentPhaseReady EnvironmentStatusSecretsPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSecretsPhaseContentPhaseUpdating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseFailed EnvironmentStatusSecretsPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSecretsPhaseContentPhaseUnavailable EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNAVAILABLE"` - `SecretName string` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `SSHPublicKeys []EnvironmentStatusSSHPublicKey` ssh_public_keys contains the status of the environment ssh public keys - `ID string` id is the unique identifier of the public key - `Phase EnvironmentStatusSSHPublicKeysPhase` phase is the current phase of the public key - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnspecified EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseCreating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseInitializing EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseReady EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUpdating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseFailed EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnavailable EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNAVAILABLE"` - `StatusVersion string` version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `WarningMessage []string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Environment Activity Signal - `type EnvironmentActivitySignal struct{…}` EnvironmentActivitySignal used to signal activity for an environment. - `Source string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `Timestamp Time` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. ### Environment Metadata - `type EnvironmentMetadata struct{…}` EnvironmentMetadata is data associated with an environment that's required for other parts of the system to function - `Annotations map[string, string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `ArchivedAt Time` Time when the Environment was archived. If not set, the environment is not archived. - `CreatedAt Time` Time when the Environment was created. - `Creator Subject` creator is the identity of the creator of the environment - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `LastStartedAt Time` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `LockdownAt Time` 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 string` name is the name of the environment as specified by the user - `OrganizationID string` organization_id is the ID of the organization that contains the environment - `OriginalContextURL string` original_context_url is the normalized URL from which the environment was created - `PrebuildID 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 string` If the Environment was started from a project, the project_id will reference the project. - `Role EnvironmentRole` role is the role of the environment - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` - `RunnerID string` Runner is the ID of the runner that runs this environment. ### Environment Phase - `type EnvironmentPhase string` - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` ### Environment Role - `type EnvironmentRole string` EnvironmentRole represents the role of an environment - `const EnvironmentRoleUnspecified EnvironmentRole = "ENVIRONMENT_ROLE_UNSPECIFIED"` - `const EnvironmentRoleDefault EnvironmentRole = "ENVIRONMENT_ROLE_DEFAULT"` - `const EnvironmentRolePrebuild EnvironmentRole = "ENVIRONMENT_ROLE_PREBUILD"` - `const EnvironmentRoleWorkflow EnvironmentRole = "ENVIRONMENT_ROLE_WORKFLOW"` ### Environment Spec - `type EnvironmentSpec struct{…}` EnvironmentSpec specifies the configuration of an environment for an environment start - `Admission AdmissionLevel` admission controlls who can access the environment and its ports. - `const AdmissionLevelUnspecified AdmissionLevel = "ADMISSION_LEVEL_UNSPECIFIED"` - `const AdmissionLevelOwnerOnly AdmissionLevel = "ADMISSION_LEVEL_OWNER_ONLY"` - `const AdmissionLevelEveryone AdmissionLevel = "ADMISSION_LEVEL_EVERYONE"` - `const AdmissionLevelOrganization AdmissionLevel = "ADMISSION_LEVEL_ORGANIZATION"` - `const AdmissionLevelCreatorOnly AdmissionLevel = "ADMISSION_LEVEL_CREATOR_ONLY"` - `AutomationsFile EnvironmentSpecAutomationsFile` automations_file is the automations file spec of the environment - `AutomationsFilePath 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 string` - `TriggerFilter []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 bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Content EnvironmentSpecContent` content is the content spec of the environment - `GitEmail string` The Git email address - `GitUsername string` The Git username - `Initializer EnvironmentInitializer` initializer configures how the environment is to be initialized - `Specs []EnvironmentInitializerSpec` - `ContextURL EnvironmentInitializerSpecsContextURL` - `URL string` url is the URL from which the environment is created - `Git EnvironmentInitializerSpecsGit` - `CheckoutLocation string` a path relative to the environment root in which the code will be checked out to - `CloneTarget string` the value for the clone target mode - use depends on the target mode - `RemoteUri string` remote_uri is the Git remote origin - `TargetMode EnvironmentInitializerSpecsGitTargetMode` the target mode determines what gets checked out - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeUnspecified EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_UNSPECIFIED"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteHead EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_HEAD"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteCommit EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_COMMIT"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeLocalBranch EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_LOCAL_BRANCH"` - `const EnvironmentInitializerSpecsGitTargetModeCloneTargetModeRemoteTag EnvironmentInitializerSpecsGitTargetMode = "CLONE_TARGET_MODE_REMOTE_TAG"` - `UpstreamRemoteUri string` upstream_Remote_uri is the fork upstream of a repository - `Session string` - `DesiredPhase EnvironmentPhase` Phase is the desired phase of the environment - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `Devcontainer EnvironmentSpecDevcontainer` devcontainer is the devcontainer spec of the environment - `DefaultDevcontainerImage string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `DevcontainerFilePath 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 EnvironmentSpecDevcontainerDotfiles` 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 EnvironmentSpecDevcontainerLifecycleStage` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageUnspecified EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_UNSPECIFIED"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStageFull EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_FULL"` - `const EnvironmentSpecDevcontainerLifecycleStageLifecycleStagePrebuild EnvironmentSpecDevcontainerLifecycleStage = "LIFECYCLE_STAGE_PREBUILD"` - `Session string` - `KernelControlsConfig KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active - `Machine EnvironmentSpecMachine` machine is the machine spec of the environment - `Class string` Class denotes the class of the environment we ought to start - `Session string` - `Ports []EnvironmentSpecPort` ports is the set of ports which ought to be exposed to your network - `Admission AdmissionLevel` policy of this port - `Name string` name of this port - `Port int64` port number - `Protocol EnvironmentSpecPortsProtocol` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `const EnvironmentSpecPortsProtocolProtocolUnspecified EnvironmentSpecPortsProtocol = "PROTOCOL_UNSPECIFIED"` - `const EnvironmentSpecPortsProtocolProtocolHTTP EnvironmentSpecPortsProtocol = "PROTOCOL_HTTP"` - `const EnvironmentSpecPortsProtocolProtocolHTTPS EnvironmentSpecPortsProtocol = "PROTOCOL_HTTPS"` - `Secrets []EnvironmentSpecSecret` secrets are confidential data that is mounted into the environment - `ID string` id is the unique identifier of the secret. - `APIOnly bool` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `ContainerRegistryBasicAuthHost string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `CredentialProxy EnvironmentSpecSecretsCredentialProxy` 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 EnvironmentSpecSecretsCredentialProxyFormat` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `const EnvironmentSpecSecretsCredentialProxyFormatFormatUnspecified EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_UNSPECIFIED"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatPlain EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_PLAIN"` - `const EnvironmentSpecSecretsCredentialProxyFormatFormatBase64 EnvironmentSpecSecretsCredentialProxyFormat = "FORMAT_BASE64"` - `Header string` header is the HTTP header name to inject (e.g. "Authorization"). - `TargetHosts []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 string` - `FilePath string` file_path is the path inside the devcontainer where the secret is mounted - `GitCredentialHost string` - `Name string` name is the human readable description of the secret - `Scope EnvironmentSpecSecretsScope` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `const EnvironmentSpecSecretsScopeScopeUnspecified EnvironmentSpecSecretsScope = "SCOPE_UNSPECIFIED"` - `const EnvironmentSpecSecretsScopeScopeOrganization EnvironmentSpecSecretsScope = "SCOPE_ORGANIZATION"` - `const EnvironmentSpecSecretsScopeScopeProject EnvironmentSpecSecretsScope = "SCOPE_PROJECT"` - `const EnvironmentSpecSecretsScopeScopeUser EnvironmentSpecSecretsScope = "SCOPE_USER"` - `const EnvironmentSpecSecretsScopeScopeServiceAccount EnvironmentSpecSecretsScope = "SCOPE_SERVICE_ACCOUNT"` - `const EnvironmentSpecSecretsScopeScopeRunner EnvironmentSpecSecretsScope = "SCOPE_RUNNER"` - `Session string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `Source string` source is the source of the secret, for now control-plane or runner - `SourceRef string` source_ref into the source, in case of control-plane this is uuid of the secret - `SpecVersion 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 []EnvironmentSpecSSHPublicKey` ssh_public_keys are the public keys used to ssh into the environment - `ID string` id is the unique identifier of the public key - `Value string` value is the actual public key in the public key file format - `Timeout EnvironmentSpecTimeout` Timeout configures the environment timeout - `Disconnected 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 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 - `type EnvironmentStatus struct{…}` EnvironmentStatus describes an environment status - `ActivitySignal EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `Source string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `Timestamp Time` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `AutomationsFile EnvironmentStatusAutomationsFile` automations_file contains the status of the automations file. - `AutomationsFilePath string` automations_file_path is the path to the automations file relative to the repo root. - `AutomationsFilePresence EnvironmentStatusAutomationsFileAutomationsFilePresence` automations_file_presence indicates how an automations file is present in the environment. - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceUnspecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceAbsent EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_ABSENT"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceDiscovered EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusAutomationsFileAutomationsFilePresencePresenceSpecified EnvironmentStatusAutomationsFileAutomationsFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `Phase EnvironmentStatusAutomationsFilePhase` phase is the current phase of the automations file. - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnspecified EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseCreating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseInitializing EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseReady EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUpdating EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseFailed EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusAutomationsFilePhaseContentPhaseUnavailable EnvironmentStatusAutomationsFilePhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the automations file session that is currently applied in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `Content EnvironmentStatusContent` content contains the status of the environment content. - `ContentLocationInMachine string` content_location_in_machine is the location of the content in the machine - `FailureMessage string` failure_message contains the reason the content initialization failed. - `Git EnvironmentStatusContentGit` 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 string` branch is branch we're currently on - `ChangedFiles []EnvironmentStatusContentGitChangedFile` changed_files is an array of changed files in the environment, possibly truncated - `ChangeType EnvironmentStatusContentGitChangedFilesChangeType` ChangeType is the type of change that happened to the file - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUnspecified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNSPECIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeAdded EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_ADDED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeModified EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_MODIFIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeDeleted EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_DELETED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeRenamed EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_RENAMED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeCopied EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_COPIED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUpdatedButUnmerged EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UPDATED_BUT_UNMERGED"` - `const EnvironmentStatusContentGitChangedFilesChangeTypeChangeTypeUntracked EnvironmentStatusContentGitChangedFilesChangeType = "CHANGE_TYPE_UNTRACKED"` - `OldPath string` old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `Path string` path is the path of the file - `CloneURL string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `LatestCommit string` latest_commit is the most recent commit on the current branch - `TotalChangedFiles int64` - `TotalUnpushedCommits int64` the total number of unpushed changes - `UnpushedCommits []string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `Phase EnvironmentStatusContentPhase` phase is the current phase of the environment content - `const EnvironmentStatusContentPhaseContentPhaseUnspecified EnvironmentStatusContentPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusContentPhaseContentPhaseCreating EnvironmentStatusContentPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusContentPhaseContentPhaseInitializing EnvironmentStatusContentPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusContentPhaseContentPhaseReady EnvironmentStatusContentPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusContentPhaseContentPhaseUpdating EnvironmentStatusContentPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusContentPhaseContentPhaseFailed EnvironmentStatusContentPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusContentPhaseContentPhaseUnavailable EnvironmentStatusContentPhase = "CONTENT_PHASE_UNAVAILABLE"` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `Devcontainer EnvironmentStatusDevcontainer` devcontainer contains the status of the devcontainer. - `ContainerID string` container_id is the ID of the container. - `ContainerName string` container_name is the name of the container that is used to connect to the devcontainer - `DevcontainerconfigInSync bool` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `DevcontainerFilePath string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `DevcontainerFilePresence EnvironmentStatusDevcontainerDevcontainerFilePresence` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceUnspecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceGenerated EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_GENERATED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceDiscovered EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_DISCOVERED"` - `const EnvironmentStatusDevcontainerDevcontainerFilePresencePresenceSpecified EnvironmentStatusDevcontainerDevcontainerFilePresence = "PRESENCE_SPECIFIED"` - `FailureMessage string` failure_message contains the reason the devcontainer failed to operate. - `Phase EnvironmentStatusDevcontainerPhase` phase is the current phase of the devcontainer - `const EnvironmentStatusDevcontainerPhasePhaseUnspecified EnvironmentStatusDevcontainerPhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusDevcontainerPhasePhaseCreating EnvironmentStatusDevcontainerPhase = "PHASE_CREATING"` - `const EnvironmentStatusDevcontainerPhasePhaseRunning EnvironmentStatusDevcontainerPhase = "PHASE_RUNNING"` - `const EnvironmentStatusDevcontainerPhasePhaseStopped EnvironmentStatusDevcontainerPhase = "PHASE_STOPPED"` - `const EnvironmentStatusDevcontainerPhasePhaseFailed EnvironmentStatusDevcontainerPhase = "PHASE_FAILED"` - `RemoteUser string` remote_user is the user that is used to connect to the devcontainer - `RemoteWorkspaceFolder string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `SecretsInSync bool` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `Session string` session is the session that is currently active in the devcontainer. - `WarningMessage string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `EnvironmentURLs EnvironmentStatusEnvironmentURLs` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `Logs string` logs is the URL at which the environment logs can be accessed. - `Ops string` ops is the URL at which the environment ops service can be accessed. - `Ports []EnvironmentStatusEnvironmentURLsPort` - `Port int64` port is the port number of the environment port - `URL string` url is the URL at which the environment port can be accessed - `SSH EnvironmentStatusEnvironmentURLsSSH` SSH is the URL at which the environment can be accessed via SSH. - `URL string` - `SupportBundle string` support_bundle is the URL at which the environment support bundle can be accessed. - `FailureMessage []string` failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `Machine EnvironmentStatusMachine` machine contains the status of the environment machine - `FailureMessage string` failure_message contains the reason the machine failed to operate. - `Phase EnvironmentStatusMachinePhase` phase is the current phase of the environment machine - `const EnvironmentStatusMachinePhasePhaseUnspecified EnvironmentStatusMachinePhase = "PHASE_UNSPECIFIED"` - `const EnvironmentStatusMachinePhasePhaseCreating EnvironmentStatusMachinePhase = "PHASE_CREATING"` - `const EnvironmentStatusMachinePhasePhaseStarting EnvironmentStatusMachinePhase = "PHASE_STARTING"` - `const EnvironmentStatusMachinePhasePhaseRunning EnvironmentStatusMachinePhase = "PHASE_RUNNING"` - `const EnvironmentStatusMachinePhasePhaseStopping EnvironmentStatusMachinePhase = "PHASE_STOPPING"` - `const EnvironmentStatusMachinePhasePhaseStopped EnvironmentStatusMachinePhase = "PHASE_STOPPED"` - `const EnvironmentStatusMachinePhasePhaseDeleting EnvironmentStatusMachinePhase = "PHASE_DELETING"` - `const EnvironmentStatusMachinePhasePhaseDeleted EnvironmentStatusMachinePhase = "PHASE_DELETED"` - `Session string` session is the session that is currently active in the machine. - `Timeout string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `Versions EnvironmentStatusMachineVersions` versions contains the versions of components in the machine. - `AmiID string` - `SupervisorCommit string` - `SupervisorVersion string` - `WarningMessage string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `Phase EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `const EnvironmentPhaseUnspecified EnvironmentPhase = "ENVIRONMENT_PHASE_UNSPECIFIED"` - `const EnvironmentPhaseCreating EnvironmentPhase = "ENVIRONMENT_PHASE_CREATING"` - `const EnvironmentPhaseStarting EnvironmentPhase = "ENVIRONMENT_PHASE_STARTING"` - `const EnvironmentPhaseRunning EnvironmentPhase = "ENVIRONMENT_PHASE_RUNNING"` - `const EnvironmentPhaseUpdating EnvironmentPhase = "ENVIRONMENT_PHASE_UPDATING"` - `const EnvironmentPhaseStopping EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPING"` - `const EnvironmentPhaseStopped EnvironmentPhase = "ENVIRONMENT_PHASE_STOPPED"` - `const EnvironmentPhaseDeleting EnvironmentPhase = "ENVIRONMENT_PHASE_DELETING"` - `const EnvironmentPhaseDeleted EnvironmentPhase = "ENVIRONMENT_PHASE_DELETED"` - `RunnerAck EnvironmentStatusRunnerAck` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `Message string` - `SpecVersion string` - `StatusCode EnvironmentStatusRunnerAckStatusCode` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeUnspecified EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_UNSPECIFIED"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeOk EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_OK"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeInvalidResource EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_INVALID_RESOURCE"` - `const EnvironmentStatusRunnerAckStatusCodeStatusCodeFailedPrecondition EnvironmentStatusRunnerAckStatusCode = "STATUS_CODE_FAILED_PRECONDITION"` - `Secrets []EnvironmentStatusSecret` secrets contains the status of the environment secrets - `ID string` id is the unique identifier of the secret. - `FailureMessage string` failure_message contains the reason the secret failed to be materialize. - `Phase EnvironmentStatusSecretsPhase` - `const EnvironmentStatusSecretsPhaseContentPhaseUnspecified EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSecretsPhaseContentPhaseCreating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseInitializing EnvironmentStatusSecretsPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSecretsPhaseContentPhaseReady EnvironmentStatusSecretsPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSecretsPhaseContentPhaseUpdating EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSecretsPhaseContentPhaseFailed EnvironmentStatusSecretsPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSecretsPhaseContentPhaseUnavailable EnvironmentStatusSecretsPhase = "CONTENT_PHASE_UNAVAILABLE"` - `SecretName string` - `Session string` session is the session that is currently active in the environment. - `WarningMessage string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `SSHPublicKeys []EnvironmentStatusSSHPublicKey` ssh_public_keys contains the status of the environment ssh public keys - `ID string` id is the unique identifier of the public key - `Phase EnvironmentStatusSSHPublicKeysPhase` phase is the current phase of the public key - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnspecified EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNSPECIFIED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseCreating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_CREATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseInitializing EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_INITIALIZING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseReady EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_READY"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUpdating EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UPDATING"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseFailed EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_FAILED"` - `const EnvironmentStatusSSHPublicKeysPhaseContentPhaseUnavailable EnvironmentStatusSSHPublicKeysPhase = "CONTENT_PHASE_UNAVAILABLE"` - `StatusVersion string` version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `WarningMessage []string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Kernel Controls Config - `type KernelControlsConfig struct{…}` KernelControlsConfig configures kernel-level controls for the environment - `Veto Veto` veto controls blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active ### Veto - `type Veto struct{…}` Veto controls kernel-level blocking mechanisms - `Exec VetoExec` exec controls executable blocking - `Action KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `const KernelControlsActionUnspecified KernelControlsAction = "KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `const KernelControlsActionBlock KernelControlsAction = "KERNEL_CONTROLS_ACTION_BLOCK"` - `const KernelControlsActionAudit KernelControlsAction = "KERNEL_CONTROLS_ACTION_AUDIT"` - `Denylist []string` denylist is the list of executable paths or names to block - `Enabled bool` enabled controls whether executable blocking is active # Automations ## UpsertAutomationsFile `client.Environments.Automations.Upsert(ctx, body) (*EnvironmentAutomationUpsertResponse, error)` **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 ``` ### Parameters - `body EnvironmentAutomationUpsertParams` - `AutomationsFile param.Field[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. - `EnvironmentID param.Field[string]` ### Returns - `type EnvironmentAutomationUpsertResponse struct{…}` - `UpdatedServiceIDs []string` - `UpdatedTaskIDs []string` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Automations.Upsert(context.TODO(), gitpod.EnvironmentAutomationUpsertParams{ AutomationsFile: gitpod.F(gitpod.AutomationsFileParam{ Services: gitpod.F(map[string]gitpod.AutomationsFileServiceParam{ "web-server": gitpod.AutomationsFileServiceParam{ Commands: gitpod.F(gitpod.AutomationsFileServicesCommandsParam{ Ready: gitpod.F("curl -s http://localhost:3000"), Start: gitpod.F("npm run dev"), }), Description: gitpod.F("Development web server"), Name: gitpod.F("Web Server"), TriggeredBy: gitpod.F([]gitpod.AutomationsFileServicesTriggeredBy{gitpod.AutomationsFileServicesTriggeredByPostDevcontainerStart}), }, }), Tasks: gitpod.F(map[string]gitpod.AutomationsFileTaskParam{ "build": gitpod.AutomationsFileTaskParam{ Command: gitpod.F("npm run build"), Description: gitpod.F("Builds the project artifacts"), Name: gitpod.F("Build Project"), TriggeredBy: gitpod.F([]gitpod.AutomationsFileTasksTriggeredBy{gitpod.AutomationsFileTasksTriggeredByPostEnvironmentStart}), }, }), }), EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.UpdatedServiceIDs) } ``` #### Response ```json { "updatedServiceIds": [ "string" ], "updatedTaskIds": [ "string" ] } ``` ## Domain Types ### Automations File - `type AutomationsFile struct{…}` 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 map[string, AutomationsFileService]` - `Commands AutomationsFileServicesCommands` - `Ready 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 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 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 string` - `Name string` - `Role AutomationsFileServicesRole` - `const AutomationsFileServicesRoleEmpty AutomationsFileServicesRole = ""` - `const AutomationsFileServicesRoleDefault AutomationsFileServicesRole = "default"` - `const AutomationsFileServicesRoleEditor AutomationsFileServicesRole = "editor"` - `const AutomationsFileServicesRoleAIAgent AutomationsFileServicesRole = "ai-agent"` - `RunsOn RunsOn` - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `TriggeredBy []AutomationsFileServicesTriggeredBy` - `const AutomationsFileServicesTriggeredByManual AutomationsFileServicesTriggeredBy = "manual"` - `const AutomationsFileServicesTriggeredByPostEnvironmentStart AutomationsFileServicesTriggeredBy = "postEnvironmentStart"` - `const AutomationsFileServicesTriggeredByPostDevcontainerStart AutomationsFileServicesTriggeredBy = "postDevcontainerStart"` - `const AutomationsFileServicesTriggeredByPrebuild AutomationsFileServicesTriggeredBy = "prebuild"` - `Tasks map[string, AutomationsFileTask]` - `Command string` - `DependsOn []string` - `Description string` - `Name string` - `RunsOn RunsOn` - `TriggeredBy []AutomationsFileTasksTriggeredBy` - `const AutomationsFileTasksTriggeredByManual AutomationsFileTasksTriggeredBy = "manual"` - `const AutomationsFileTasksTriggeredByPostEnvironmentStart AutomationsFileTasksTriggeredBy = "postEnvironmentStart"` - `const AutomationsFileTasksTriggeredByPostDevcontainerStart AutomationsFileTasksTriggeredBy = "postDevcontainerStart"` - `const AutomationsFileTasksTriggeredByPrebuild AutomationsFileTasksTriggeredBy = "prebuild"` # Services ## CreateService `client.Environments.Automations.Services.New(ctx, body) (*EnvironmentAutomationServiceNewResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationServiceNewParams` - `EnvironmentID param.Field[string]` - `Metadata param.Field[ServiceMetadata]` - `Spec param.Field[ServiceSpec]` ### Returns - `type EnvironmentAutomationServiceNewResponse struct{…}` - `Service Service` - `ID string` - `EnvironmentID string` - `Metadata ServiceMetadata` - `CreatedAt Time` created_at is the time the service was created. - `Creator Subject` creator describes the principal who created the service. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `Name 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 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 ServiceRole` role specifies the intended role or purpose of the service. - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` - `TriggeredBy []AutomationTrigger` triggered_by is a list of trigger that start the service. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec ServiceSpec` - `Commands ServiceSpecCommands` commands contains the commands to start, stop and check the readiness of the service - `Ready 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 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 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 ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` - `Env []EnvironmentVariableItem` env specifies environment variables for the service. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the service should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Session 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 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 ServiceStatus` - `FailureMessage 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 string` log_url contains the URL at which the service logs can be accessed. - `Output map[string, string]` output contains the output of the service. setting an output field to empty string will unset it. - `Phase ServicePhase` phase is the current phase of the service. - `Session string` session is the current session of the service. - `StatusVersion 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 ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" "github.com/gitpod-io/gitpod-sdk-go/shared" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) service, err := client.Environments.Automations.Services.New(context.TODO(), gitpod.EnvironmentAutomationServiceNewParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), Metadata: gitpod.F(gitpod.ServiceMetadataParam{ Description: gitpod.F("Runs the development web server"), Name: gitpod.F("Web Server"), Reference: gitpod.F("web-server"), TriggeredBy: gitpod.F([]shared.AutomationTriggerParam{shared.AutomationTriggerParam{ PostDevcontainerStart: gitpod.F(true), }}), }), Spec: gitpod.F(gitpod.ServiceSpecParam{ Commands: gitpod.F(gitpod.ServiceSpecCommandsParam{ Ready: gitpod.F("curl -s http://localhost:3000"), Start: gitpod.F("npm run dev"), }), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", service.Service) } ``` #### 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 `client.Environments.Automations.Services.Delete(ctx, body) (*EnvironmentAutomationServiceDeleteResponse, error)` **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 ``` ### Parameters - `body EnvironmentAutomationServiceDeleteParams` - `ID param.Field[string]` - `Force param.Field[bool]` ### Returns - `type EnvironmentAutomationServiceDeleteResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) service, err := client.Environments.Automations.Services.Delete(context.TODO(), gitpod.EnvironmentAutomationServiceDeleteParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", service) } ``` #### Response ```json {} ``` ## ListServices `client.Environments.Automations.Services.List(ctx, params) (*ServicesPage[Service], error)` **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 ``` ### Parameters - `params EnvironmentAutomationServiceListParams` - `Token param.Field[string]` Query param - `PageSize param.Field[int64]` Query param - `Filter param.Field[EnvironmentAutomationServiceListParamsFilter]` Body param: filter contains the filter options for listing services - `EnvironmentIDs []string` environment_ids filters the response to only services of these environments - `References []string` references filters the response to only services with these references - `Roles []ServiceRole` roles filters the response to only services with these roles - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` - `ServiceIDs []string` service_ids filters the response to only services with these IDs - `Pagination param.Field[EnvironmentAutomationServiceListParamsPagination]` Body param: pagination contains the pagination options for listing services - `Token string` Token for the next set of results that was returned as next_token of a PaginationResponse - `PageSize int64` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `type Service struct{…}` - `ID string` - `EnvironmentID string` - `Metadata ServiceMetadata` - `CreatedAt Time` created_at is the time the service was created. - `Creator Subject` creator describes the principal who created the service. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `Name 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 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 ServiceRole` role specifies the intended role or purpose of the service. - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` - `TriggeredBy []AutomationTrigger` triggered_by is a list of trigger that start the service. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec ServiceSpec` - `Commands ServiceSpecCommands` commands contains the commands to start, stop and check the readiness of the service - `Ready 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 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 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 ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` - `Env []EnvironmentVariableItem` env specifies environment variables for the service. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the service should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Session 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 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 ServiceStatus` - `FailureMessage 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 string` log_url contains the URL at which the service logs can be accessed. - `Output map[string, string]` output contains the output of the service. setting an output field to empty string will unset it. - `Phase ServicePhase` phase is the current phase of the service. - `Session string` session is the current session of the service. - `StatusVersion 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 ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) page, err := client.Environments.Automations.Services.List(context.TODO(), gitpod.EnvironmentAutomationServiceListParams{ Filter: gitpod.F(gitpod.EnvironmentAutomationServiceListParamsFilter{ References: gitpod.F([]string{"web-server", "database"}), }), Pagination: gitpod.F(gitpod.EnvironmentAutomationServiceListParamsPagination{ PageSize: gitpod.F(int64(20)), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 `client.Environments.Automations.Services.Get(ctx, body) (*EnvironmentAutomationServiceGetResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationServiceGetParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationServiceGetResponse struct{…}` - `Service Service` - `ID string` - `EnvironmentID string` - `Metadata ServiceMetadata` - `CreatedAt Time` created_at is the time the service was created. - `Creator Subject` creator describes the principal who created the service. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `Name 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 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 ServiceRole` role specifies the intended role or purpose of the service. - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` - `TriggeredBy []AutomationTrigger` triggered_by is a list of trigger that start the service. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec ServiceSpec` - `Commands ServiceSpecCommands` commands contains the commands to start, stop and check the readiness of the service - `Ready 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 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 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 ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` - `Env []EnvironmentVariableItem` env specifies environment variables for the service. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the service should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Session 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 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 ServiceStatus` - `FailureMessage 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 string` log_url contains the URL at which the service logs can be accessed. - `Output map[string, string]` output contains the output of the service. setting an output field to empty string will unset it. - `Phase ServicePhase` phase is the current phase of the service. - `Session string` session is the current session of the service. - `StatusVersion 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 ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) service, err := client.Environments.Automations.Services.Get(context.TODO(), gitpod.EnvironmentAutomationServiceGetParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", service.Service) } ``` #### 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 `client.Environments.Automations.Services.Start(ctx, body) (*EnvironmentAutomationServiceStartResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationServiceStartParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationServiceStartResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Automations.Services.Start(context.TODO(), gitpod.EnvironmentAutomationServiceStartParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` ## StopService `client.Environments.Automations.Services.Stop(ctx, body) (*EnvironmentAutomationServiceStopResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationServiceStopParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationServiceStopResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Automations.Services.Stop(context.TODO(), gitpod.EnvironmentAutomationServiceStopParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` ## UpdateService `client.Environments.Automations.Services.Update(ctx, body) (*EnvironmentAutomationServiceUpdateResponse, error)` **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 ``` ### Parameters - `body EnvironmentAutomationServiceUpdateParams` - `ID param.Field[string]` - `Metadata param.Field[EnvironmentAutomationServiceUpdateParamsMetadata]` - `Description string` - `Name string` - `Role ServiceRole` - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` - `TriggeredBy EnvironmentAutomationServiceUpdateParamsMetadataTriggeredBy` - `Trigger []AutomationTrigger` - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec param.Field[EnvironmentAutomationServiceUpdateParamsSpec]` 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 EnvironmentAutomationServiceUpdateParamsSpecCommands` - `Ready string` - `Start string` - `Stop string` - `Env []EnvironmentVariableItem` - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Status param.Field[EnvironmentAutomationServiceUpdateParamsStatus]` 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 string` - `LogURL string` - `Output map[string, string]` setting an output field to empty string will unset it. - `Phase ServicePhase` - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` - `Session string` ### Returns - `type EnvironmentAutomationServiceUpdateResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) service, err := client.Environments.Automations.Services.Update(context.TODO(), gitpod.EnvironmentAutomationServiceUpdateParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), Spec: gitpod.F(gitpod.EnvironmentAutomationServiceUpdateParamsSpec{ Commands: gitpod.F(gitpod.EnvironmentAutomationServiceUpdateParamsSpecCommands{ Ready: gitpod.F("curl -s http://localhost:8080"), Start: gitpod.F("npm run start:dev"), }), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", service) } ``` #### Response ```json {} ``` ## Domain Types ### Service - `type Service struct{…}` - `ID string` - `EnvironmentID string` - `Metadata ServiceMetadata` - `CreatedAt Time` created_at is the time the service was created. - `Creator Subject` creator describes the principal who created the service. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `Name 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 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 ServiceRole` role specifies the intended role or purpose of the service. - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` - `TriggeredBy []AutomationTrigger` triggered_by is a list of trigger that start the service. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec ServiceSpec` - `Commands ServiceSpecCommands` commands contains the commands to start, stop and check the readiness of the service - `Ready 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 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 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 ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` - `Env []EnvironmentVariableItem` env specifies environment variables for the service. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the service should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Session 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 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 ServiceStatus` - `FailureMessage 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 string` log_url contains the URL at which the service logs can be accessed. - `Output map[string, string]` output contains the output of the service. setting an output field to empty string will unset it. - `Phase ServicePhase` phase is the current phase of the service. - `Session string` session is the current session of the service. - `StatusVersion 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 - `type ServiceMetadata struct{…}` - `CreatedAt Time` created_at is the time the service was created. - `Creator Subject` creator describes the principal who created the service. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `Name 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 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 ServiceRole` role specifies the intended role or purpose of the service. - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` - `TriggeredBy []AutomationTrigger` triggered_by is a list of trigger that start the service. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` ### Service Phase - `type ServicePhase string` - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` ### Service Role - `type ServiceRole string` - `const ServiceRoleUnspecified ServiceRole = "SERVICE_ROLE_UNSPECIFIED"` - `const ServiceRoleDefault ServiceRole = "SERVICE_ROLE_DEFAULT"` - `const ServiceRoleEditor ServiceRole = "SERVICE_ROLE_EDITOR"` - `const ServiceRoleAIAgent ServiceRole = "SERVICE_ROLE_AI_AGENT"` - `const ServiceRoleSecurityAgent ServiceRole = "SERVICE_ROLE_SECURITY_AGENT"` ### Service Spec - `type ServiceSpec struct{…}` - `Commands ServiceSpecCommands` commands contains the commands to start, stop and check the readiness of the service - `Ready 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 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 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 ServicePhase` desired_phase is the phase the service should be in. Used to start or stop the service. - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` - `Env []EnvironmentVariableItem` env specifies environment variables for the service. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the service should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Session 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 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 - `type ServiceStatus struct{…}` - `FailureMessage 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 string` log_url contains the URL at which the service logs can be accessed. - `Output map[string, string]` output contains the output of the service. setting an output field to empty string will unset it. - `Phase ServicePhase` phase is the current phase of the service. - `const ServicePhaseUnspecified ServicePhase = "SERVICE_PHASE_UNSPECIFIED"` - `const ServicePhaseStarting ServicePhase = "SERVICE_PHASE_STARTING"` - `const ServicePhaseRunning ServicePhase = "SERVICE_PHASE_RUNNING"` - `const ServicePhaseStopping ServicePhase = "SERVICE_PHASE_STOPPING"` - `const ServicePhaseStopped ServicePhase = "SERVICE_PHASE_STOPPED"` - `const ServicePhaseFailed ServicePhase = "SERVICE_PHASE_FAILED"` - `const ServicePhaseDeleted ServicePhase = "SERVICE_PHASE_DELETED"` - `Session string` session is the current session of the service. - `StatusVersion 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. # Tasks ## CreateTask `client.Environments.Automations.Tasks.New(ctx, body) (*EnvironmentAutomationTaskNewResponse, error)` **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"] ``` ### Parameters - `body EnvironmentAutomationTaskNewParams` - `DependsOn param.Field[[]string]` - `EnvironmentID param.Field[string]` - `Metadata param.Field[TaskMetadata]` - `Spec param.Field[TaskSpec]` ### Returns - `type EnvironmentAutomationTaskNewResponse struct{…}` - `Task Task` - `ID string` - `DependsOn []string` dependencies specifies the IDs of the automations this task depends on. - `EnvironmentID string` - `Metadata TaskMetadata` - `CreatedAt Time` created_at is the time the task was created. - `Creator Subject` creator describes the principal who created the task. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `Name 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 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 []AutomationTrigger` triggered_by is a list of trigger that start the task. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec TaskSpec` - `Command string` command contains the command the task should execute - `Env []EnvironmentVariableItem` env specifies environment variables for the task. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the task should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" "github.com/gitpod-io/gitpod-sdk-go/shared" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) task, err := client.Environments.Automations.Tasks.New(context.TODO(), gitpod.EnvironmentAutomationTaskNewParams{ EnvironmentID: gitpod.F("07e03a28-65a5-4d98-b532-8ea67b188048"), Metadata: gitpod.F(shared.TaskMetadataParam{ Description: gitpod.F("Builds the project artifacts"), Name: gitpod.F("Build Project"), Reference: gitpod.F("build"), TriggeredBy: gitpod.F([]shared.AutomationTriggerParam{shared.AutomationTriggerParam{ PostEnvironmentStart: gitpod.F(true), }}), }), Spec: gitpod.F(shared.TaskSpecParam{ Command: gitpod.F("npm run build"), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", task.Task) } ``` #### 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 `client.Environments.Automations.Tasks.Delete(ctx, body) (*EnvironmentAutomationTaskDeleteResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationTaskDeleteParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationTaskDeleteResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) task, err := client.Environments.Automations.Tasks.Delete(context.TODO(), gitpod.EnvironmentAutomationTaskDeleteParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", task) } ``` #### Response ```json {} ``` ## ListTasks `client.Environments.Automations.Tasks.List(ctx, params) (*TasksPage[Task], error)` **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 ``` ### Parameters - `params EnvironmentAutomationTaskListParams` - `Token param.Field[string]` Query param - `PageSize param.Field[int64]` Query param - `Filter param.Field[EnvironmentAutomationTaskListParamsFilter]` Body param: filter contains the filter options for listing tasks - `EnvironmentIDs []string` environment_ids filters the response to only tasks of these environments - `References []string` references filters the response to only services with these references - `TaskIDs []string` task_ids filters the response to only tasks with these IDs - `Pagination param.Field[EnvironmentAutomationTaskListParamsPagination]` Body param: pagination contains the pagination options for listing tasks - `Token string` Token for the next set of results that was returned as next_token of a PaginationResponse - `PageSize int64` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `type Task struct{…}` - `ID string` - `DependsOn []string` dependencies specifies the IDs of the automations this task depends on. - `EnvironmentID string` - `Metadata TaskMetadata` - `CreatedAt Time` created_at is the time the task was created. - `Creator Subject` creator describes the principal who created the task. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `Name 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 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 []AutomationTrigger` triggered_by is a list of trigger that start the task. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec TaskSpec` - `Command string` command contains the command the task should execute - `Env []EnvironmentVariableItem` env specifies environment variables for the task. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the task should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) page, err := client.Environments.Automations.Tasks.List(context.TODO(), gitpod.EnvironmentAutomationTaskListParams{ Filter: gitpod.F(gitpod.EnvironmentAutomationTaskListParamsFilter{ References: gitpod.F([]string{"build", "test"}), }), Pagination: gitpod.F(gitpod.EnvironmentAutomationTaskListParamsPagination{ PageSize: gitpod.F(int64(20)), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 `client.Environments.Automations.Tasks.Get(ctx, body) (*EnvironmentAutomationTaskGetResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationTaskGetParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationTaskGetResponse struct{…}` - `Task Task` - `ID string` - `DependsOn []string` dependencies specifies the IDs of the automations this task depends on. - `EnvironmentID string` - `Metadata TaskMetadata` - `CreatedAt Time` created_at is the time the task was created. - `Creator Subject` creator describes the principal who created the task. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `Description string` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `Name 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 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 []AutomationTrigger` triggered_by is a list of trigger that start the task. - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec TaskSpec` - `Command string` command contains the command the task should execute - `Env []EnvironmentVariableItem` env specifies environment variables for the task. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the task should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) task, err := client.Environments.Automations.Tasks.Get(context.TODO(), gitpod.EnvironmentAutomationTaskGetParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", task.Task) } ``` #### 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 `client.Environments.Automations.Tasks.Start(ctx, body) (*EnvironmentAutomationTaskStartResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationTaskStartParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationTaskStartResponse struct{…}` - `TaskExecution TaskExecution` - `ID string` - `Metadata TaskExecutionMetadata` - `CompletedAt Time` completed_at is the time the task execution was done. - `CreatedAt Time` created_at is the time the task was created. - `Creator Subject` creator describes the principal who created/started the task run. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `EnvironmentID string` environment_id is the ID of the environment in which the task run is executed. - `StartedAt Time` started_at is the time the task execution actually started to run. - `StartedBy string` started_by describes the trigger that started the task execution. - `TaskID string` task_id is the ID of the main task being executed. - `Spec TaskExecutionSpec` - `DesiredPhase TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `const TaskExecutionPhaseUnspecified TaskExecutionPhase = "TASK_EXECUTION_PHASE_UNSPECIFIED"` - `const TaskExecutionPhasePending TaskExecutionPhase = "TASK_EXECUTION_PHASE_PENDING"` - `const TaskExecutionPhaseRunning TaskExecutionPhase = "TASK_EXECUTION_PHASE_RUNNING"` - `const TaskExecutionPhaseSucceeded TaskExecutionPhase = "TASK_EXECUTION_PHASE_SUCCEEDED"` - `const TaskExecutionPhaseFailed TaskExecutionPhase = "TASK_EXECUTION_PHASE_FAILED"` - `const TaskExecutionPhaseStopped TaskExecutionPhase = "TASK_EXECUTION_PHASE_STOPPED"` - `Plan []TaskExecutionSpecPlan` 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 []TaskExecutionSpecPlanStep` - `ID string` ID is the ID of the execution step - `DependsOn []string` - `Label string` - `ServiceID string` - `Task TaskExecutionSpecPlanStepsTask` - `ID string` - `Spec TaskSpec` - `Command string` command contains the command the task should execute - `Env []EnvironmentVariableItem` env specifies environment variables for the task. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the task should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Status TaskExecutionStatus` - `FailureMessage 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 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 TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `StatusVersion 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 []TaskExecutionStatusStep` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `ID string` ID is the ID of the execution step - `FailureMessage 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 map[string, string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `Phase TaskExecutionPhase` phase is the current phase of the execution step ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Automations.Tasks.Start(context.TODO(), gitpod.EnvironmentAutomationTaskStartParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.TaskExecution) } ``` #### 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 `client.Environments.Automations.Tasks.Update(ctx, body) (*EnvironmentAutomationTaskUpdateResponse, error)` **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 ``` ### Parameters - `body EnvironmentAutomationTaskUpdateParams` - `ID param.Field[string]` - `DependsOn param.Field[[]string]` dependencies specifies the IDs of the automations this task depends on. - `Metadata param.Field[EnvironmentAutomationTaskUpdateParamsMetadata]` - `Description string` - `Name string` - `TriggeredBy EnvironmentAutomationTaskUpdateParamsMetadataTriggeredBy` - `Trigger []AutomationTrigger` - `BeforeSnapshot bool` - `Manual bool` - `PostDevcontainerStart bool` - `PostEnvironmentStart bool` - `PostMachineStart bool` - `Prebuild bool` - `Spec param.Field[EnvironmentAutomationTaskUpdateParamsSpec]` - `Command string` - `Env []EnvironmentVariableItem` - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. ### Returns - `type EnvironmentAutomationTaskUpdateResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) task, err := client.Environments.Automations.Tasks.Update(context.TODO(), gitpod.EnvironmentAutomationTaskUpdateParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), Spec: gitpod.F(gitpod.EnvironmentAutomationTaskUpdateParamsSpec{ Command: gitpod.F("npm run test:coverage"), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", task) } ``` #### Response ```json {} ``` # Executions ## ListTaskExecutions `client.Environments.Automations.Tasks.Executions.List(ctx, params) (*TaskExecutionsPage[TaskExecution], error)` **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 ``` ### Parameters - `params EnvironmentAutomationTaskExecutionListParams` - `Token param.Field[string]` Query param - `PageSize param.Field[int64]` Query param - `Filter param.Field[EnvironmentAutomationTaskExecutionListParamsFilter]` Body param: filter contains the filter options for listing task runs - `EnvironmentIDs []string` environment_ids filters the response to only task runs of these environments - `Phases []TaskExecutionPhase` phases filters the response to only task runs in these phases - `const TaskExecutionPhaseUnspecified TaskExecutionPhase = "TASK_EXECUTION_PHASE_UNSPECIFIED"` - `const TaskExecutionPhasePending TaskExecutionPhase = "TASK_EXECUTION_PHASE_PENDING"` - `const TaskExecutionPhaseRunning TaskExecutionPhase = "TASK_EXECUTION_PHASE_RUNNING"` - `const TaskExecutionPhaseSucceeded TaskExecutionPhase = "TASK_EXECUTION_PHASE_SUCCEEDED"` - `const TaskExecutionPhaseFailed TaskExecutionPhase = "TASK_EXECUTION_PHASE_FAILED"` - `const TaskExecutionPhaseStopped TaskExecutionPhase = "TASK_EXECUTION_PHASE_STOPPED"` - `TaskIDs []string` task_ids filters the response to only task runs of these tasks - `TaskReferences []string` task_references filters the response to only task runs with this reference - `Pagination param.Field[EnvironmentAutomationTaskExecutionListParamsPagination]` Body param: pagination contains the pagination options for listing task runs - `Token string` Token for the next set of results that was returned as next_token of a PaginationResponse - `PageSize int64` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `type TaskExecution struct{…}` - `ID string` - `Metadata TaskExecutionMetadata` - `CompletedAt Time` completed_at is the time the task execution was done. - `CreatedAt Time` created_at is the time the task was created. - `Creator Subject` creator describes the principal who created/started the task run. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `EnvironmentID string` environment_id is the ID of the environment in which the task run is executed. - `StartedAt Time` started_at is the time the task execution actually started to run. - `StartedBy string` started_by describes the trigger that started the task execution. - `TaskID string` task_id is the ID of the main task being executed. - `Spec TaskExecutionSpec` - `DesiredPhase TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `const TaskExecutionPhaseUnspecified TaskExecutionPhase = "TASK_EXECUTION_PHASE_UNSPECIFIED"` - `const TaskExecutionPhasePending TaskExecutionPhase = "TASK_EXECUTION_PHASE_PENDING"` - `const TaskExecutionPhaseRunning TaskExecutionPhase = "TASK_EXECUTION_PHASE_RUNNING"` - `const TaskExecutionPhaseSucceeded TaskExecutionPhase = "TASK_EXECUTION_PHASE_SUCCEEDED"` - `const TaskExecutionPhaseFailed TaskExecutionPhase = "TASK_EXECUTION_PHASE_FAILED"` - `const TaskExecutionPhaseStopped TaskExecutionPhase = "TASK_EXECUTION_PHASE_STOPPED"` - `Plan []TaskExecutionSpecPlan` 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 []TaskExecutionSpecPlanStep` - `ID string` ID is the ID of the execution step - `DependsOn []string` - `Label string` - `ServiceID string` - `Task TaskExecutionSpecPlanStepsTask` - `ID string` - `Spec TaskSpec` - `Command string` command contains the command the task should execute - `Env []EnvironmentVariableItem` env specifies environment variables for the task. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the task should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Status TaskExecutionStatus` - `FailureMessage 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 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 TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `StatusVersion 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 []TaskExecutionStatusStep` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `ID string` ID is the ID of the execution step - `FailureMessage 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 map[string, string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `Phase TaskExecutionPhase` phase is the current phase of the execution step ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" "github.com/gitpod-io/gitpod-sdk-go/shared" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) page, err := client.Environments.Automations.Tasks.Executions.List(context.TODO(), gitpod.EnvironmentAutomationTaskExecutionListParams{ Filter: gitpod.F(gitpod.EnvironmentAutomationTaskExecutionListParamsFilter{ Phases: gitpod.F([]shared.TaskExecutionPhase{shared.TaskExecutionPhaseRunning, shared.TaskExecutionPhaseFailed}), }), Pagination: gitpod.F(gitpod.EnvironmentAutomationTaskExecutionListParamsPagination{ PageSize: gitpod.F(int64(20)), }), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### 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 `client.Environments.Automations.Tasks.Executions.Get(ctx, body) (*EnvironmentAutomationTaskExecutionGetResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationTaskExecutionGetParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationTaskExecutionGetResponse struct{…}` - `TaskExecution TaskExecution` - `ID string` - `Metadata TaskExecutionMetadata` - `CompletedAt Time` completed_at is the time the task execution was done. - `CreatedAt Time` created_at is the time the task was created. - `Creator Subject` creator describes the principal who created/started the task run. - `ID string` id is the UUID of the subject - `Principal Principal` Principal is the principal of the subject - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"` - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"` - `const PrincipalUser Principal = "PRINCIPAL_USER"` - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"` - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"` - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"` - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"` - `EnvironmentID string` environment_id is the ID of the environment in which the task run is executed. - `StartedAt Time` started_at is the time the task execution actually started to run. - `StartedBy string` started_by describes the trigger that started the task execution. - `TaskID string` task_id is the ID of the main task being executed. - `Spec TaskExecutionSpec` - `DesiredPhase TaskExecutionPhase` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `const TaskExecutionPhaseUnspecified TaskExecutionPhase = "TASK_EXECUTION_PHASE_UNSPECIFIED"` - `const TaskExecutionPhasePending TaskExecutionPhase = "TASK_EXECUTION_PHASE_PENDING"` - `const TaskExecutionPhaseRunning TaskExecutionPhase = "TASK_EXECUTION_PHASE_RUNNING"` - `const TaskExecutionPhaseSucceeded TaskExecutionPhase = "TASK_EXECUTION_PHASE_SUCCEEDED"` - `const TaskExecutionPhaseFailed TaskExecutionPhase = "TASK_EXECUTION_PHASE_FAILED"` - `const TaskExecutionPhaseStopped TaskExecutionPhase = "TASK_EXECUTION_PHASE_STOPPED"` - `Plan []TaskExecutionSpecPlan` 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 []TaskExecutionSpecPlanStep` - `ID string` ID is the ID of the execution step - `DependsOn []string` - `Label string` - `ServiceID string` - `Task TaskExecutionSpecPlanStepsTask` - `ID string` - `Spec TaskSpec` - `Command string` command contains the command the task should execute - `Env []EnvironmentVariableItem` env specifies environment variables for the task. - `Name string` name is the environment variable name. - `Value string` value is a literal string value. - `ValueFrom EnvironmentVariableSource` value_from specifies a source for the value. - `SecretRef SecretRef` secret_ref references a secret by ID. - `ID string` id is the UUID of the secret to reference. - `RunsOn RunsOn` runs_on specifies the environment the task should run on. - `Docker RunsOnDocker` - `Environment []string` - `Image string` - `Machine unknown` Machine runs the service/task directly on the VM/machine level. - `Status TaskExecutionStatus` - `FailureMessage 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 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 TaskExecutionPhase` the phase of a task execution represents the aggregated phase of all steps. - `StatusVersion 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 []TaskExecutionStatusStep` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `ID string` ID is the ID of the execution step - `FailureMessage 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 map[string, string]` output contains the output of the task execution. setting an output field to empty string will unset it. - `Phase TaskExecutionPhase` phase is the current phase of the execution step ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) execution, err := client.Environments.Automations.Tasks.Executions.Get(context.TODO(), gitpod.EnvironmentAutomationTaskExecutionGetParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", execution.TaskExecution) } ``` #### 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 `client.Environments.Automations.Tasks.Executions.Stop(ctx, body) (*EnvironmentAutomationTaskExecutionStopResponse, error)` **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" ``` ### Parameters - `body EnvironmentAutomationTaskExecutionStopParams` - `ID param.Field[string]` ### Returns - `type EnvironmentAutomationTaskExecutionStopResponse interface{…}` ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) response, err := client.Environments.Automations.Tasks.Executions.Stop(context.TODO(), gitpod.EnvironmentAutomationTaskExecutionStopParams{ ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response) } ``` #### Response ```json {} ``` # Classes ## ListEnvironmentClasses `client.Environments.Classes.List(ctx, params) (*EnvironmentClassesPage[EnvironmentClass], error)` **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 ### Parameters - `params EnvironmentClassListParams` - `Token param.Field[string]` Query param - `PageSize param.Field[int64]` Query param - `Filter param.Field[EnvironmentClassListParamsFilter]` Body param - `CanCreateEnvironments bool` 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 bool` enabled filters the response to only enabled or disabled environment classes. If not set, all environment classes are returned. - `RunnerIDs []string` runner_ids filters the response to only EnvironmentClasses of these Runner IDs - `RunnerKinds []RunnerKind` runner_kind filters the response to only environment classes from runners of these kinds. - `const RunnerKindUnspecified RunnerKind = "RUNNER_KIND_UNSPECIFIED"` - `const RunnerKindLocal RunnerKind = "RUNNER_KIND_LOCAL"` - `const RunnerKindRemote RunnerKind = "RUNNER_KIND_REMOTE"` - `const RunnerKindLocalConfiguration RunnerKind = "RUNNER_KIND_LOCAL_CONFIGURATION"` - `RunnerProviders []RunnerProvider` runner_providers filters the response to only environment classes from runners of these providers. - `const RunnerProviderUnspecified RunnerProvider = "RUNNER_PROVIDER_UNSPECIFIED"` - `const RunnerProviderAwsEc2 RunnerProvider = "RUNNER_PROVIDER_AWS_EC2"` - `const RunnerProviderLinuxHost RunnerProvider = "RUNNER_PROVIDER_LINUX_HOST"` - `const RunnerProviderDesktopMac RunnerProvider = "RUNNER_PROVIDER_DESKTOP_MAC"` - `const RunnerProviderManaged RunnerProvider = "RUNNER_PROVIDER_MANAGED"` - `const RunnerProviderGcp RunnerProvider = "RUNNER_PROVIDER_GCP"` - `const RunnerProviderDevAgent RunnerProvider = "RUNNER_PROVIDER_DEV_AGENT"` - `Pagination param.Field[EnvironmentClassListParamsPagination]` Body param: pagination contains the pagination options for listing environment classes - `Token string` Token for the next set of results that was returned as next_token of a PaginationResponse - `PageSize int64` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `type EnvironmentClass struct{…}` - `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 []FieldValue` configuration describes the configuration of the environment class - `Key string` - `Value string` - `Description string` description is a human readable description of the environment class - `DisplayName string` display_name is the human readable name of the environment class - `Enabled bool` enabled indicates whether the environment class can be used to create new environments. ### Example ```go package main import ( "context" "fmt" "github.com/gitpod-io/gitpod-sdk-go" "github.com/gitpod-io/gitpod-sdk-go/option" ) func main() { client := gitpod.NewClient( option.WithBearerToken("My Bearer Token"), ) page, err := client.Environments.Classes.List(context.TODO(), gitpod.EnvironmentClassListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "environmentClasses": [ { "id": "id", "runnerId": "runnerId", "configuration": [ { "key": "key", "value": "value" } ], "description": "xxx", "displayName": "xxx", "enabled": true } ], "pagination": { "nextToken": "nextToken" } } ```