## CreateEnvironment **post** `/gitpod.v1.EnvironmentService/CreateEnvironment` Creates a development environment from a context URL (e.g. Git repository) and starts it. The `class` field must be a valid environment class ID. You can find a list of available environment classes with the `ListEnvironmentClasses` method. ### Examples - Create from context URL: Creates an environment from a Git repository URL with default settings. ```yaml spec: machine: class: "d2c94c27-3b76-4a42-b88c-95a85e392c68" content: initializer: specs: - contextUrl: url: "https://github.com/gitpod-io/gitpod" ``` - Create from Git repository: Creates an environment from a Git repository with specific branch targeting. ```yaml spec: machine: class: "d2c94c27-3b76-4a42-b88c-95a85e392c68" content: initializer: specs: - git: remoteUri: "https://github.com/gitpod-io/gitpod" cloneTarget: "main" targetMode: "CLONE_TARGET_MODE_REMOTE_BRANCH" ``` - Create with custom timeout and ports: Creates an environment with custom inactivity timeout and exposed port configuration. ```yaml spec: machine: class: "d2c94c27-3b76-4a42-b88c-95a85e392c68" content: initializer: specs: - contextUrl: url: "https://github.com/gitpod-io/gitpod" timeout: disconnected: "7200s" # 2 hours in seconds ports: - port: 3000 admission: "ADMISSION_LEVEL_EVERYONE" name: "Web App" ``` ### Body Parameters - `name: optional string` name is a user-defined identifier for the environment. If not specified, the system will generate a name. - `sessionId: optional string` session_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly. - `spec: optional EnvironmentSpec` spec is the configuration of the environment that's required for the to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"ENVIRONMENT_PHASE_UNSPECIFIED"` - `"ENVIRONMENT_PHASE_CREATING"` - `"ENVIRONMENT_PHASE_STARTING"` - `"ENVIRONMENT_PHASE_RUNNING"` - `"ENVIRONMENT_PHASE_UPDATING"` - `"ENVIRONMENT_PHASE_STOPPING"` - `"ENVIRONMENT_PHASE_STOPPED"` - `"ENVIRONMENT_PHASE_DELETING"` - `"ENVIRONMENT_PHASE_DELETED"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. ### Returns - `environment: Environment` +resource get environment - `id: string` ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager - `metadata: optional EnvironmentMetadata` Metadata is data associated with this environment that's required for other parts of Gitpod to function - `annotations: optional map[string]` annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented - `archivedAt: optional string` Time when the Environment was archived. If not set, the environment is not archived. - `createdAt: optional string` Time when the Environment was created. - `creator: optional Subject` creator is the identity of the creator of the environment - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `lastStartedAt: optional string` Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called). - `lockdownAt: optional string` lockdown_at is the time at which the environment becomes locked down due to the organization's maximum environment lifetime policy. Nil when no lifetime policy applies. - `name: optional string` name is the name of the environment as specified by the user - `organizationId: optional string` organization_id is the ID of the organization that contains the environment - `originalContextUrl: optional string` original_context_url is the normalized URL from which the environment was created - `prebuildId: optional string` prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. - `projectId: optional string` If the Environment was started from a project, the project_id will reference the project. - `role: optional EnvironmentRole` role is the role of the environment - `"ENVIRONMENT_ROLE_UNSPECIFIED"` - `"ENVIRONMENT_ROLE_DEFAULT"` - `"ENVIRONMENT_ROLE_PREBUILD"` - `"ENVIRONMENT_ROLE_WORKFLOW"` - `runnerId: optional string` Runner is the ID of the runner that runs this environment. - `spec: optional EnvironmentSpec` Spec is the configuration of the environment that's required for the runner to start the environment - `admission: optional AdmissionLevel` admission controlls who can access the environment and its ports. - `"ADMISSION_LEVEL_UNSPECIFIED"` - `"ADMISSION_LEVEL_OWNER_ONLY"` - `"ADMISSION_LEVEL_EVERYONE"` - `"ADMISSION_LEVEL_ORGANIZATION"` - `"ADMISSION_LEVEL_CREATOR_ONLY"` - `automationsFile: optional object { automationsFilePath, session, triggerFilter }` automations_file is the automations file spec of the environment - `automationsFilePath: optional string` automations_file_path is the path to the automations file that is applied in the environment, relative to the repo root. path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `session: optional string` - `triggerFilter: optional array of AutomationTrigger` trigger_filter specifies which automation triggers should execute. When set, only automations matching these triggers will run. If empty/unset, all triggers are evaluated normally. - `beforeSnapshot: optional boolean` - `manual: optional boolean` - `postDevcontainerStart: optional boolean` - `postEnvironmentStart: optional boolean` - `postMachineStart: optional boolean` - `prebuild: optional boolean` - `content: optional object { gitEmail, gitUsername, initializer, session }` content is the content spec of the environment - `gitEmail: optional string` The Git email address - `gitUsername: optional string` The Git username - `initializer: optional EnvironmentInitializer` initializer configures how the environment is to be initialized - `specs: optional array of object { contextUrl, git }` - `contextUrl: optional object { url }` - `url: optional string` url is the URL from which the environment is created - `git: optional object { checkoutLocation, cloneTarget, remoteUri, 2 more }` - `checkoutLocation: optional string` a path relative to the environment root in which the code will be checked out to - `cloneTarget: optional string` the value for the clone target mode - use depends on the target mode - `remoteUri: optional string` remote_uri is the Git remote origin - `targetMode: optional "CLONE_TARGET_MODE_UNSPECIFIED" or "CLONE_TARGET_MODE_REMOTE_HEAD" or "CLONE_TARGET_MODE_REMOTE_COMMIT" or 3 more` the target mode determines what gets checked out - `"CLONE_TARGET_MODE_UNSPECIFIED"` - `"CLONE_TARGET_MODE_REMOTE_HEAD"` - `"CLONE_TARGET_MODE_REMOTE_COMMIT"` - `"CLONE_TARGET_MODE_REMOTE_BRANCH"` - `"CLONE_TARGET_MODE_LOCAL_BRANCH"` - `"CLONE_TARGET_MODE_REMOTE_TAG"` - `upstreamRemoteUri: optional string` upstream_Remote_uri is the fork upstream of a repository - `session: optional string` - `desiredPhase: optional EnvironmentPhase` Phase is the desired phase of the environment - `"ENVIRONMENT_PHASE_UNSPECIFIED"` - `"ENVIRONMENT_PHASE_CREATING"` - `"ENVIRONMENT_PHASE_STARTING"` - `"ENVIRONMENT_PHASE_RUNNING"` - `"ENVIRONMENT_PHASE_UPDATING"` - `"ENVIRONMENT_PHASE_STOPPING"` - `"ENVIRONMENT_PHASE_STOPPED"` - `"ENVIRONMENT_PHASE_DELETING"` - `"ENVIRONMENT_PHASE_DELETED"` - `devcontainer: optional object { defaultDevcontainerImage, devcontainerFilePath, dotfiles, 2 more }` devcontainer is the devcontainer spec of the environment - `defaultDevcontainerImage: optional string` default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `dotfiles: optional object { repository }` Experimental: dotfiles is the dotfiles configuration of the devcontainer - `repository: string` URL of a dotfiles Git repository (e.g. https://github.com/owner/repository) - `lifecycleStage: optional "LIFECYCLE_STAGE_UNSPECIFIED" or "LIFECYCLE_STAGE_FULL" or "LIFECYCLE_STAGE_PREBUILD"` lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. - `"LIFECYCLE_STAGE_UNSPECIFIED"` - `"LIFECYCLE_STAGE_FULL"` - `"LIFECYCLE_STAGE_PREBUILD"` - `session: optional string` - `kernelControlsConfig: optional KernelControlsConfig` kernel_controls_config configures kernel-level controls for this environment - `veto: optional Veto` veto controls blocking mechanisms - `exec: optional object { action, denylist, enabled }` exec controls executable blocking - `action: optional KernelControlsAction` action specifies what action kernel-level controls take on policy violations - `"KERNEL_CONTROLS_ACTION_UNSPECIFIED"` - `"KERNEL_CONTROLS_ACTION_BLOCK"` - `"KERNEL_CONTROLS_ACTION_AUDIT"` - `denylist: optional array of string` denylist is the list of executable paths or names to block - `enabled: optional boolean` enabled controls whether executable blocking is active - `machine: optional object { class, session }` machine is the machine spec of the environment - `class: optional string` Class denotes the class of the environment we ought to start - `session: optional string` - `ports: optional array of object { admission, name, port, protocol }` ports is the set of ports which ought to be exposed to your network - `admission: optional AdmissionLevel` policy of this port - `name: optional string` name of this port - `port: optional number` port number - `protocol: optional "PROTOCOL_UNSPECIFIED" or "PROTOCOL_HTTP" or "PROTOCOL_HTTPS"` protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services. - `"PROTOCOL_UNSPECIFIED"` - `"PROTOCOL_HTTP"` - `"PROTOCOL_HTTPS"` - `secrets: optional array of object { id, apiOnly, containerRegistryBasicAuthHost, 9 more }` secrets are confidential data that is mounted into the environment - `id: optional string` id is the unique identifier of the secret. - `apiOnly: optional boolean` api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers. - `containerRegistryBasicAuthHost: optional string` container_registry_basic_auth_host is the hostname of the container registry that supports basic auth - `credentialProxy: optional object { format, header, targetHosts }` credential_proxy configures transparent credential injection via the credential proxy. When set, the credential proxy intercepts HTTPS traffic to the target hosts and replaces the dummy secret value with the real value in the specified HTTP header. The real secret value is never exposed in the environment. This field is orthogonal to mount — a secret can be both mounted (e.g. as a git credential) and proxied at the same time. - `format: optional "FORMAT_UNSPECIFIED" or "FORMAT_PLAIN" or "FORMAT_BASE64"` format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header. - `"FORMAT_UNSPECIFIED"` - `"FORMAT_PLAIN"` - `"FORMAT_BASE64"` - `header: optional string` header is the HTTP header name to inject (e.g. "Authorization"). - `targetHosts: optional array of string` target_hosts lists the hostnames to intercept (for example "github.com" or "*.github.com"). Wildcards are subdomain-only and do not match the apex domain. - `environmentVariable: optional string` - `filePath: optional string` file_path is the path inside the devcontainer where the secret is mounted - `gitCredentialHost: optional string` - `name: optional string` name is the human readable description of the secret - `scope: optional "SCOPE_UNSPECIFIED" or "SCOPE_ORGANIZATION" or "SCOPE_PROJECT" or 3 more` scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected). - `"SCOPE_UNSPECIFIED"` - `"SCOPE_ORGANIZATION"` - `"SCOPE_PROJECT"` - `"SCOPE_USER"` - `"SCOPE_SERVICE_ACCOUNT"` - `"SCOPE_RUNNER"` - `session: optional string` session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment. - `source: optional string` source is the source of the secret, for now control-plane or runner - `sourceRef: optional string` source_ref into the source, in case of control-plane this is uuid of the secret - `specVersion: optional string` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `sshPublicKeys: optional array of object { id, value }` ssh_public_keys are the public keys used to ssh into the environment - `id: optional string` id is the unique identifier of the public key - `value: optional string` value is the actual public key in the public key file format - `timeout: optional object { disconnected }` Timeout configures the environment timeout - `disconnected: optional string` inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. value must be 0s (disabled) or at least 1800s (30 minutes): ``` this == duration('0s') || this >= duration('1800s') ``` - `workflowActionId: optional string` workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. - `status: optional EnvironmentStatus` Status is the current status of the environment - `activitySignal: optional EnvironmentActivitySignal` activity_signal is the last activity signal for the environment. - `source: optional string` source of the activity signal, such as "VS Code", "SSH", or "Automations". It should be a human-readable string that describes the source of the activity signal. - `timestamp: optional string` timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed. - `automationsFile: optional object { automationsFilePath, automationsFilePresence, failureMessage, 3 more }` automations_file contains the status of the automations file. - `automationsFilePath: optional string` automations_file_path is the path to the automations file relative to the repo root. - `automationsFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_ABSENT" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` automations_file_presence indicates how an automations file is present in the environment. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_ABSENT"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the automations file. - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the automations file session that is currently applied in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when no triggers are defined in the automations file. - `content: optional object { contentLocationInMachine, failureMessage, git, 3 more }` content contains the status of the environment content. - `contentLocationInMachine: optional string` content_location_in_machine is the location of the content in the machine - `failureMessage: optional string` failure_message contains the reason the content initialization failed. - `git: optional object { branch, changedFiles, cloneUrl, 4 more }` git is the Git working copy status of the environment. Note: this is a best-effort field and more often than not will not be present. Its absence does not indicate the absence of a working copy. - `branch: optional string` branch is branch we're currently on - `changedFiles: optional array of object { changeType, oldPath, path }` changed_files is an array of changed files in the environment, possibly truncated - `changeType: optional "CHANGE_TYPE_UNSPECIFIED" or "CHANGE_TYPE_ADDED" or "CHANGE_TYPE_MODIFIED" or 5 more` ChangeType is the type of change that happened to the file - `"CHANGE_TYPE_UNSPECIFIED"` - `"CHANGE_TYPE_ADDED"` - `"CHANGE_TYPE_MODIFIED"` - `"CHANGE_TYPE_DELETED"` - `"CHANGE_TYPE_RENAMED"` - `"CHANGE_TYPE_COPIED"` - `"CHANGE_TYPE_UPDATED_BUT_UNMERGED"` - `"CHANGE_TYPE_UNTRACKED"` - `oldPath: optional string` old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED. - `path: optional string` path is the path of the file - `cloneUrl: optional string` clone_url is the repository url as you would pass it to "git clone". Only HTTPS clone URLs are supported. - `latestCommit: optional string` latest_commit is the most recent commit on the current branch - `totalChangedFiles: optional number` - `totalUnpushedCommits: optional number` the total number of unpushed changes - `unpushedCommits: optional array of string` unpushed_commits is an array of unpushed changes in the environment, possibly truncated - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the environment content - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the content is present but not in the expected state. - `devcontainer: optional object { containerId, containerName, devcontainerconfigInSync, 9 more }` devcontainer contains the status of the devcontainer. - `containerId: optional string` container_id is the ID of the container. - `containerName: optional string` container_name is the name of the container that is used to connect to the devcontainer - `devcontainerconfigInSync: optional boolean` devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file. - `devcontainerFilePath: optional string` devcontainer_file_path is the path to the devcontainer file relative to the repo root - `devcontainerFilePresence: optional "PRESENCE_UNSPECIFIED" or "PRESENCE_GENERATED" or "PRESENCE_DISCOVERED" or "PRESENCE_SPECIFIED"` devcontainer_file_presence indicates how the devcontainer file is present in the repo. - `"PRESENCE_UNSPECIFIED"` - `"PRESENCE_GENERATED"` - `"PRESENCE_DISCOVERED"` - `"PRESENCE_SPECIFIED"` - `failureMessage: optional string` failure_message contains the reason the devcontainer failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_RUNNING" or 2 more` phase is the current phase of the devcontainer - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPED"` - `"PHASE_FAILED"` - `remoteUser: optional string` remote_user is the user that is used to connect to the devcontainer - `remoteWorkspaceFolder: optional string` remote_workspace_folder is the folder that is used to connect to the devcontainer - `secretsInSync: optional boolean` secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer. - `session: optional string` session is the session that is currently active in the devcontainer. - `warningMessage: optional string` warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state. - `environmentUrls: optional object { logs, ops, ports, 2 more }` environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running. - `logs: optional string` logs is the URL at which the environment logs can be accessed. - `ops: optional string` ops is the URL at which the environment ops service can be accessed. - `ports: optional array of object { port, url }` - `port: optional number` port is the port number of the environment port - `url: optional string` url is the URL at which the environment port can be accessed - `ssh: optional object { url }` SSH is the URL at which the environment can be accessed via SSH. - `url: optional string` - `supportBundle: optional string` support_bundle is the URL at which the environment support bundle can be accessed. - `failureMessage: optional array of string` failure_message summarises why the environment failed to operate. If this is non-empty the environment has failed to operate and will likely transition to a stopped state. - `machine: optional object { failureMessage, phase, session, 3 more }` machine contains the status of the environment machine - `failureMessage: optional string` failure_message contains the reason the machine failed to operate. - `phase: optional "PHASE_UNSPECIFIED" or "PHASE_CREATING" or "PHASE_STARTING" or 5 more` phase is the current phase of the environment machine - `"PHASE_UNSPECIFIED"` - `"PHASE_CREATING"` - `"PHASE_STARTING"` - `"PHASE_RUNNING"` - `"PHASE_STOPPING"` - `"PHASE_STOPPED"` - `"PHASE_DELETING"` - `"PHASE_DELETED"` - `session: optional string` session is the session that is currently active in the machine. - `timeout: optional string` timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out. - `versions: optional object { amiId, supervisorCommit, supervisorVersion }` versions contains the versions of components in the machine. - `amiId: optional string` - `supervisorCommit: optional string` - `supervisorVersion: optional string` - `warningMessage: optional string` warning_message contains warnings, e.g. when the machine is present but not in the expected state. - `phase: optional EnvironmentPhase` the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle - `runnerAck: optional object { message, specVersion, statusCode }` runner_ack contains the acknowledgement from the runner that is has received the environment spec. - `message: optional string` - `specVersion: optional string` - `statusCode: optional "STATUS_CODE_UNSPECIFIED" or "STATUS_CODE_OK" or "STATUS_CODE_INVALID_RESOURCE" or "STATUS_CODE_FAILED_PRECONDITION"` - `"STATUS_CODE_UNSPECIFIED"` - `"STATUS_CODE_OK"` - `"STATUS_CODE_INVALID_RESOURCE"` - `"STATUS_CODE_FAILED_PRECONDITION"` - `secrets: optional array of object { id, failureMessage, phase, 3 more }` secrets contains the status of the environment secrets - `id: optional string` id is the unique identifier of the secret. - `failureMessage: optional string` failure_message contains the reason the secret failed to be materialize. - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `secretName: optional string` - `session: optional string` session is the session that is currently active in the environment. - `warningMessage: optional string` warning_message contains warnings, e.g. when the secret is present but not in the expected state. - `sshPublicKeys: optional array of object { id, phase }` ssh_public_keys contains the status of the environment ssh public keys - `id: optional string` id is the unique identifier of the public key - `phase: optional "CONTENT_PHASE_UNSPECIFIED" or "CONTENT_PHASE_CREATING" or "CONTENT_PHASE_INITIALIZING" or 4 more` phase is the current phase of the public key - `"CONTENT_PHASE_UNSPECIFIED"` - `"CONTENT_PHASE_CREATING"` - `"CONTENT_PHASE_INITIALIZING"` - `"CONTENT_PHASE_READY"` - `"CONTENT_PHASE_UPDATING"` - `"CONTENT_PHASE_FAILED"` - `"CONTENT_PHASE_UNAVAILABLE"` - `statusVersion: optional string` version of the status update. Environment instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `warningMessage: optional array of string` warning_message contains warnings, e.g. when the environment is present but not in the expected state. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.EnvironmentService/CreateEnvironment \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "environment": { "id": "id", "metadata": { "annotations": { "foo": "string" }, "archivedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "lastStartedAt": "2019-12-27T18:11:19.117Z", "lockdownAt": "2019-12-27T18:11:19.117Z", "name": "name", "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "originalContextUrl": "originalContextUrl", "prebuildId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "projectId", "role": "ENVIRONMENT_ROLE_UNSPECIFIED", "runnerId": "runnerId", "sessionId": "sessionId" }, "spec": { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "automationsFile": { "automationsFilePath": "automationsFilePath", "session": "session", "triggerFilter": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "content": { "gitEmail": "gitEmail", "gitUsername": "gitUsername", "initializer": { "specs": [ { "contextUrl": { "url": "https://example.com" }, "git": { "checkoutLocation": "checkoutLocation", "cloneTarget": "cloneTarget", "remoteUri": "remoteUri", "targetMode": "CLONE_TARGET_MODE_UNSPECIFIED", "upstreamRemoteUri": "upstreamRemoteUri" } } ] }, "session": "session" }, "desiredPhase": "ENVIRONMENT_PHASE_UNSPECIFIED", "devcontainer": { "defaultDevcontainerImage": "defaultDevcontainerImage", "devcontainerFilePath": "devcontainerFilePath", "dotfiles": { "repository": "https://example.com" }, "lifecycleStage": "LIFECYCLE_STAGE_UNSPECIFIED", "session": "session" }, "kernelControlsConfig": { "bpfDebugLevel": "BPF_DEBUG_LEVEL_UNSPECIFIED", "veto": { "exec": { "action": "KERNEL_CONTROLS_ACTION_UNSPECIFIED", "denyBlockDevices": true, "denylist": [ "string" ], "enabled": true, "resolveBareNames": true, "untouchable": true, "watch": true } } }, "machine": { "class": "class", "preferDualDisk": true, "session": "session" }, "ports": [ { "admission": "ADMISSION_LEVEL_UNSPECIFIED", "authNonce": "authNonce", "name": "x", "port": 1024, "protocol": "PROTOCOL_UNSPECIFIED" } ], "secrets": [ { "id": "id", "apiOnly": true, "containerRegistryBasicAuthHost": "containerRegistryBasicAuthHost", "credentialProxy": { "format": "FORMAT_UNSPECIFIED", "header": "header", "targetHosts": [ "string" ] }, "environmentVariable": "environmentVariable", "filePath": "filePath", "gitCredentialHost": "gitCredentialHost", "name": "name", "scope": "SCOPE_UNSPECIFIED", "session": "session", "source": "source", "sourceRef": "sourceRef" } ], "specVersion": "specVersion", "sshPublicKeys": [ { "id": "id", "value": "value" } ], "timeout": { "disconnected": "+9125115.360s" }, "workflowActionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "status": { "activitySignal": { "source": "xxx", "timestamp": "2019-12-27T18:11:19.117Z" }, "automationsFile": { "automationsFilePath": "automationsFilePath", "automationsFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "content": { "contentLocationInMachine": "contentLocationInMachine", "failureMessage": "failureMessage", "git": { "branch": "branch", "changedFiles": [ { "changeType": "CHANGE_TYPE_UNSPECIFIED", "oldPath": "oldPath", "path": "path" } ], "cloneUrl": "cloneUrl", "latestCommit": "latestCommit", "totalChangedFiles": 0, "totalUnpushedCommits": 0, "unpushedCommits": [ "string" ] }, "phase": "CONTENT_PHASE_UNSPECIFIED", "session": "session", "warningMessage": "warningMessage" }, "devcontainer": { "containerId": "containerId", "containerName": "containerName", "devcontainerconfigInSync": true, "devcontainerFilePath": "devcontainerFilePath", "devcontainerFilePresence": "PRESENCE_UNSPECIFIED", "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "remoteUser": "remoteUser", "remoteWorkspaceFolder": "remoteWorkspaceFolder", "secretsInSync": true, "session": "session", "warningMessage": "warningMessage" }, "environmentUrls": { "logs": "logs", "ops": "ops", "ports": [ { "port": 1024, "url": "url" } ], "ssh": { "url": "url" }, "supportBundle": "supportBundle", "vmLiveUsage": "vmLiveUsage" }, "failureMessage": [ "string" ], "machine": { "dualDisk": true, "failureMessage": "failureMessage", "phase": "PHASE_UNSPECIFIED", "session": "session", "timeout": "timeout", "versions": { "amiId": "amiId", "supervisorCommit": "supervisorCommit", "supervisorVersion": "supervisorVersion" }, "warningMessage": "warningMessage" }, "phase": "ENVIRONMENT_PHASE_UNSPECIFIED", "runnerAck": { "message": "message", "specVersion": "specVersion", "statusCode": "STATUS_CODE_UNSPECIFIED" }, "secrets": [ { "id": "id", "failureMessage": "failureMessage", "phase": "CONTENT_PHASE_UNSPECIFIED", "secretName": "secretName", "session": "session", "warningMessage": "warningMessage" } ], "sshPublicKeys": [ { "id": "id", "phase": "CONTENT_PHASE_UNSPECIFIED" } ], "statusVersion": "statusVersion", "warningMessage": [ "string" ] } } } ```