## 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" ] } } } ```