Skip to content
Ona API Reference
Ona Docs
API Reference
Environments

CreateEnvironmentFromProject

environments.create_from_project(EnvironmentCreateFromProjectParams**kwargs) -> EnvironmentCreateFromProjectResponse
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.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"

  • Create with custom compute resources:

    Creates an environment from project with custom machine class and timeout settings.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
spec:
  machine:
    class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  timeout:
    disconnected: "14400s"  # 4 hours in seconds
ParametersExpand Collapse
name: Optional[str]

name is a user-defined identifier for the environment. If not specified, the system will generate a name.

maxLength80
project_id: Optional[str]
formatuuid
session_id: Optional[str]

session_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly.

formatuuid
spec: Optional[EnvironmentSpecParam]

Spec is the configuration of the environment that’s required for the runner to start the environment Configuration already defined in the Project will override parts of the spec, if set

admission: Optional[AdmissionLevel]

admission controlls who can access the environment and its ports.

One of the following:
"ADMISSION_LEVEL_UNSPECIFIED"
"ADMISSION_LEVEL_OWNER_ONLY"
"ADMISSION_LEVEL_EVERYONE"
"ADMISSION_LEVEL_ORGANIZATION"
"ADMISSION_LEVEL_CREATOR_ONLY"
automations_file: Optional[AutomationsFile]

automations_file is the automations file spec of the environment

automations_file_path: Optional[str]

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[str]
trigger_filter: Optional[List[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.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
content: Optional[Content]

content is the content spec of the environment

git_email: Optional[str]

The Git email address

git_username: Optional[str]

The Git username

initializer: Optional[EnvironmentInitializer]

initializer configures how the environment is to be initialized

specs: Optional[List[Spec]]
context_url: Optional[SpecContextURL]
url: Optional[str]

url is the URL from which the environment is created

formaturi
git: Optional[SpecGit]
checkout_location: Optional[str]

a path relative to the environment root in which the code will be checked out to

clone_target: Optional[str]

the value for the clone target mode - use depends on the target mode

remote_uri: Optional[str]

remote_uri is the Git remote origin

target_mode: Optional[Literal["CLONE_TARGET_MODE_UNSPECIFIED", "CLONE_TARGET_MODE_REMOTE_HEAD", "CLONE_TARGET_MODE_REMOTE_COMMIT", 3 more]]

the target mode determines what gets checked out

One of the following:
"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"
upstream_remote_uri: Optional[str]

upstream_Remote_uri is the fork upstream of a repository

session: Optional[str]
desired_phase: Optional[EnvironmentPhase]

Phase is the desired phase of the environment

One of the following:
"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[Devcontainer]

devcontainer is the devcontainer spec of the environment

default_devcontainer_image: Optional[str]

default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found

devcontainer_file_path: Optional[str]

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[DevcontainerDotfiles]

Experimental: dotfiles is the dotfiles configuration of the devcontainer

repository: str

URL of a dotfiles Git repository (e.g. https://github.com/owner/repository)

formaturi
lifecycle_stage: Optional[Literal["LIFECYCLE_STAGE_UNSPECIFIED", "LIFECYCLE_STAGE_FULL", "LIFECYCLE_STAGE_PREBUILD"]]

lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified.

One of the following:
"LIFECYCLE_STAGE_UNSPECIFIED"
"LIFECYCLE_STAGE_FULL"
"LIFECYCLE_STAGE_PREBUILD"
session: Optional[str]
kernel_controls_config: Optional[KernelControlsConfig]

kernel_controls_config configures kernel-level controls for this environment

veto: Optional[Veto]

veto controls blocking mechanisms

exec: Optional[Exec]

exec controls executable blocking

action: Optional[KernelControlsAction]

action specifies what action kernel-level controls take on policy violations

One of the following:
"KERNEL_CONTROLS_ACTION_UNSPECIFIED"
"KERNEL_CONTROLS_ACTION_BLOCK"
"KERNEL_CONTROLS_ACTION_AUDIT"
denylist: Optional[List[str]]

denylist is the list of executable paths or names to block

enabled: Optional[bool]

enabled controls whether executable blocking is active

machine: Optional[Machine]

machine is the machine spec of the environment

class_: Optional[str]

Class denotes the class of the environment we ought to start

session: Optional[str]
ports: Optional[List[Port]]

ports is the set of ports which ought to be exposed to your network

admission: Optional[AdmissionLevel]

policy of this port

One of the following:
"ADMISSION_LEVEL_UNSPECIFIED"
"ADMISSION_LEVEL_OWNER_ONLY"
"ADMISSION_LEVEL_EVERYONE"
"ADMISSION_LEVEL_ORGANIZATION"
"ADMISSION_LEVEL_CREATOR_ONLY"
name: Optional[str]

name of this port

maxLength100
minLength1
port: Optional[int]

port number

formatint32
maximum65535
minimum1024
protocol: Optional[Literal["PROTOCOL_UNSPECIFIED", "PROTOCOL_HTTP", "PROTOCOL_HTTPS"]]

protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services.

One of the following:
"PROTOCOL_UNSPECIFIED"
"PROTOCOL_HTTP"
"PROTOCOL_HTTPS"
secrets: Optional[List[Secret]]

secrets are confidential data that is mounted into the environment

id: Optional[str]

id is the unique identifier of the secret.

api_only: Optional[bool]

api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.

container_registry_basic_auth_host: Optional[str]

container_registry_basic_auth_host is the hostname of the container registry that supports basic auth

credential_proxy: Optional[SecretCredentialProxy]

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[Literal["FORMAT_UNSPECIFIED", "FORMAT_PLAIN", "FORMAT_BASE64"]]

format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header.

One of the following:
"FORMAT_UNSPECIFIED"
"FORMAT_PLAIN"
"FORMAT_BASE64"
header: Optional[str]

header is the HTTP header name to inject (e.g. “Authorization”).

target_hosts: Optional[List[str]]

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.

environment_variable: Optional[str]
file_path: Optional[str]

file_path is the path inside the devcontainer where the secret is mounted

git_credential_host: Optional[str]
name: Optional[str]

name is the human readable description of the secret

scope: Optional[Literal["SCOPE_UNSPECIFIED", "SCOPE_ORGANIZATION", "SCOPE_PROJECT", 3 more]]

scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).

One of the following:
"SCOPE_UNSPECIFIED"
"SCOPE_ORGANIZATION"
"SCOPE_PROJECT"
"SCOPE_USER"
"SCOPE_SERVICE_ACCOUNT"
"SCOPE_RUNNER"
session: Optional[str]

session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment.

source: Optional[str]

source is the source of the secret, for now control-plane or runner

source_ref: Optional[str]

source_ref into the source, in case of control-plane this is uuid of the secret

spec_version: Optional[str]

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.

ssh_public_keys: Optional[List[SSHPublicKey]]

ssh_public_keys are the public keys used to ssh into the environment

id: Optional[str]

id is the unique identifier of the public key

value: Optional[str]

value is the actual public key in the public key file format

timeout: Optional[Timeout]

Timeout configures the environment timeout

disconnected: Optional[str]

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')
formatregex
workflow_action_id: Optional[str]

workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation.

formatuuid
ReturnsExpand Collapse
class EnvironmentCreateFromProjectResponse: …
environment: Environment

+resource get environment

id: str

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[Dict[str, str]]

annotations are key/value pairs that gets attached to the environment. +internal - not yet implemented

archived_at: Optional[datetime]

Time when the Environment was archived. If not set, the environment is not archived.

formatdate-time
created_at: Optional[datetime]

Time when the Environment was created.

formatdate-time
creator: Optional[Subject]

creator is the identity of the creator of the environment

id: Optional[str]

id is the UUID of the subject

formatuuid
principal: Optional[Principal]

Principal is the principal of the subject

One of the following:
"PRINCIPAL_UNSPECIFIED"
"PRINCIPAL_ACCOUNT"
"PRINCIPAL_USER"
"PRINCIPAL_RUNNER"
"PRINCIPAL_ENVIRONMENT"
"PRINCIPAL_SERVICE_ACCOUNT"
"PRINCIPAL_RUNNER_MANAGER"
last_started_at: Optional[datetime]

Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called).

formatdate-time
lockdown_at: Optional[datetime]

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.

formatdate-time
name: Optional[str]

name is the name of the environment as specified by the user

maxLength80
organization_id: Optional[str]

organization_id is the ID of the organization that contains the environment

formatuuid
original_context_url: Optional[str]

original_context_url is the normalized URL from which the environment was created

prebuild_id: Optional[str]

prebuild_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild.

formatuuid
project_id: Optional[str]

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

One of the following:
"ENVIRONMENT_ROLE_UNSPECIFIED"
"ENVIRONMENT_ROLE_DEFAULT"
"ENVIRONMENT_ROLE_PREBUILD"
"ENVIRONMENT_ROLE_WORKFLOW"
runner_id: Optional[str]

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.

One of the following:
"ADMISSION_LEVEL_UNSPECIFIED"
"ADMISSION_LEVEL_OWNER_ONLY"
"ADMISSION_LEVEL_EVERYONE"
"ADMISSION_LEVEL_ORGANIZATION"
"ADMISSION_LEVEL_CREATOR_ONLY"
automations_file: Optional[AutomationsFile]

automations_file is the automations file spec of the environment

automations_file_path: Optional[str]

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[str]
trigger_filter: Optional[List[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.

before_snapshot: Optional[bool]
manual: Optional[bool]
post_devcontainer_start: Optional[bool]
post_environment_start: Optional[bool]
post_machine_start: Optional[bool]
prebuild: Optional[bool]
content: Optional[Content]

content is the content spec of the environment

git_email: Optional[str]

The Git email address

git_username: Optional[str]

The Git username

initializer: Optional[EnvironmentInitializer]

initializer configures how the environment is to be initialized

specs: Optional[List[Spec]]
context_url: Optional[SpecContextURL]
url: Optional[str]

url is the URL from which the environment is created

formaturi
git: Optional[SpecGit]
checkout_location: Optional[str]

a path relative to the environment root in which the code will be checked out to

clone_target: Optional[str]

the value for the clone target mode - use depends on the target mode

remote_uri: Optional[str]

remote_uri is the Git remote origin

target_mode: Optional[Literal["CLONE_TARGET_MODE_UNSPECIFIED", "CLONE_TARGET_MODE_REMOTE_HEAD", "CLONE_TARGET_MODE_REMOTE_COMMIT", 3 more]]

the target mode determines what gets checked out

One of the following:
"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"
upstream_remote_uri: Optional[str]

upstream_Remote_uri is the fork upstream of a repository

session: Optional[str]
desired_phase: Optional[EnvironmentPhase]

Phase is the desired phase of the environment

One of the following:
"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[Devcontainer]

devcontainer is the devcontainer spec of the environment

default_devcontainer_image: Optional[str]

default_devcontainer_image is the default image that is used to start the devcontainer if no devcontainer config file is found

devcontainer_file_path: Optional[str]

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[DevcontainerDotfiles]

Experimental: dotfiles is the dotfiles configuration of the devcontainer

repository: str

URL of a dotfiles Git repository (e.g. https://github.com/owner/repository)

formaturi
lifecycle_stage: Optional[Literal["LIFECYCLE_STAGE_UNSPECIFIED", "LIFECYCLE_STAGE_FULL", "LIFECYCLE_STAGE_PREBUILD"]]

lifecycle_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified.

One of the following:
"LIFECYCLE_STAGE_UNSPECIFIED"
"LIFECYCLE_STAGE_FULL"
"LIFECYCLE_STAGE_PREBUILD"
session: Optional[str]
kernel_controls_config: Optional[KernelControlsConfig]

kernel_controls_config configures kernel-level controls for this environment

veto: Optional[Veto]

veto controls blocking mechanisms

exec: Optional[Exec]

exec controls executable blocking

action: Optional[KernelControlsAction]

action specifies what action kernel-level controls take on policy violations

One of the following:
"KERNEL_CONTROLS_ACTION_UNSPECIFIED"
"KERNEL_CONTROLS_ACTION_BLOCK"
"KERNEL_CONTROLS_ACTION_AUDIT"
denylist: Optional[List[str]]

denylist is the list of executable paths or names to block

enabled: Optional[bool]

enabled controls whether executable blocking is active

machine: Optional[Machine]

machine is the machine spec of the environment

class_: Optional[str]

Class denotes the class of the environment we ought to start

session: Optional[str]
ports: Optional[List[Port]]

ports is the set of ports which ought to be exposed to your network

admission: Optional[AdmissionLevel]

policy of this port

One of the following:
"ADMISSION_LEVEL_UNSPECIFIED"
"ADMISSION_LEVEL_OWNER_ONLY"
"ADMISSION_LEVEL_EVERYONE"
"ADMISSION_LEVEL_ORGANIZATION"
"ADMISSION_LEVEL_CREATOR_ONLY"
name: Optional[str]

name of this port

maxLength100
minLength1
port: Optional[int]

port number

formatint32
maximum65535
minimum1024
protocol: Optional[Literal["PROTOCOL_UNSPECIFIED", "PROTOCOL_HTTP", "PROTOCOL_HTTPS"]]

protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services.

One of the following:
"PROTOCOL_UNSPECIFIED"
"PROTOCOL_HTTP"
"PROTOCOL_HTTPS"
secrets: Optional[List[Secret]]

secrets are confidential data that is mounted into the environment

id: Optional[str]

id is the unique identifier of the secret.

api_only: Optional[bool]

api_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.

container_registry_basic_auth_host: Optional[str]

container_registry_basic_auth_host is the hostname of the container registry that supports basic auth

credential_proxy: Optional[SecretCredentialProxy]

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[Literal["FORMAT_UNSPECIFIED", "FORMAT_PLAIN", "FORMAT_BASE64"]]

format describes how the secret value is encoded. The proxy uses this to decode the value before injecting it into the header.

One of the following:
"FORMAT_UNSPECIFIED"
"FORMAT_PLAIN"
"FORMAT_BASE64"
header: Optional[str]

header is the HTTP header name to inject (e.g. “Authorization”).

target_hosts: Optional[List[str]]

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.

environment_variable: Optional[str]
file_path: Optional[str]

file_path is the path inside the devcontainer where the secret is mounted

git_credential_host: Optional[str]
name: Optional[str]

name is the human readable description of the secret

scope: Optional[Literal["SCOPE_UNSPECIFIED", "SCOPE_ORGANIZATION", "SCOPE_PROJECT", 3 more]]

scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).

One of the following:
"SCOPE_UNSPECIFIED"
"SCOPE_ORGANIZATION"
"SCOPE_PROJECT"
"SCOPE_USER"
"SCOPE_SERVICE_ACCOUNT"
"SCOPE_RUNNER"
session: Optional[str]

session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment.

source: Optional[str]

source is the source of the secret, for now control-plane or runner

source_ref: Optional[str]

source_ref into the source, in case of control-plane this is uuid of the secret

spec_version: Optional[str]

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.

ssh_public_keys: Optional[List[SSHPublicKey]]

ssh_public_keys are the public keys used to ssh into the environment

id: Optional[str]

id is the unique identifier of the public key

value: Optional[str]

value is the actual public key in the public key file format

timeout: Optional[Timeout]

Timeout configures the environment timeout

disconnected: Optional[str]

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')
formatregex
workflow_action_id: Optional[str]

workflow_action_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation.

formatuuid
status: Optional[EnvironmentStatus]

Status is the current status of the environment

activity_signal: Optional[EnvironmentActivitySignal]

activity_signal is the last activity signal for the environment.

source: Optional[str]

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.

maxLength80
minLength3
timestamp: Optional[datetime]

timestamp of when the activity was observed by the source. Only reported every 5 minutes. Zero value means no activity was observed.

formatdate-time
automations_file: Optional[AutomationsFile]

automations_file contains the status of the automations file.

automations_file_path: Optional[str]

automations_file_path is the path to the automations file relative to the repo root.

automations_file_presence: Optional[Literal["PRESENCE_UNSPECIFIED", "PRESENCE_ABSENT", "PRESENCE_DISCOVERED", "PRESENCE_SPECIFIED"]]

automations_file_presence indicates how an automations file is present in the environment.

One of the following:
"PRESENCE_UNSPECIFIED"
"PRESENCE_ABSENT"
"PRESENCE_DISCOVERED"
"PRESENCE_SPECIFIED"
failure_message: Optional[str]

failure_message contains the reason the automations file failed to be applied. This is only set if the phase is FAILED.

phase: Optional[Literal["CONTENT_PHASE_UNSPECIFIED", "CONTENT_PHASE_CREATING", "CONTENT_PHASE_INITIALIZING", 4 more]]

phase is the current phase of the automations file.

One of the following:
"CONTENT_PHASE_UNSPECIFIED"
"CONTENT_PHASE_CREATING"
"CONTENT_PHASE_INITIALIZING"
"CONTENT_PHASE_READY"
"CONTENT_PHASE_UPDATING"
"CONTENT_PHASE_FAILED"
"CONTENT_PHASE_UNAVAILABLE"
session: Optional[str]

session is the automations file session that is currently applied in the environment.

warning_message: Optional[str]

warning_message contains warnings, e.g. when no triggers are defined in the automations file.

content: Optional[Content]

content contains the status of the environment content.

content_location_in_machine: Optional[str]

content_location_in_machine is the location of the content in the machine

failure_message: Optional[str]

failure_message contains the reason the content initialization failed.

git: Optional[ContentGit]

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[str]

branch is branch we’re currently on

changed_files: Optional[List[ContentGitChangedFile]]

changed_files is an array of changed files in the environment, possibly truncated

change_type: Optional[Literal["CHANGE_TYPE_UNSPECIFIED", "CHANGE_TYPE_ADDED", "CHANGE_TYPE_MODIFIED", 5 more]]

ChangeType is the type of change that happened to the file

One of the following:
"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"
old_path: Optional[str]

old_path is the previous path of the file before a rename or copy. Only set when change_type is RENAMED or COPIED.

maxLength255
path: Optional[str]

path is the path of the file

maxLength255
clone_url: Optional[str]

clone_url is the repository url as you would pass it to “git clone”. Only HTTPS clone URLs are supported.

latest_commit: Optional[str]

latest_commit is the most recent commit on the current branch

total_changed_files: Optional[int]
formatint32
total_unpushed_commits: Optional[int]

the total number of unpushed changes

formatint32
unpushed_commits: Optional[List[str]]

unpushed_commits is an array of unpushed changes in the environment, possibly truncated

phase: Optional[Literal["CONTENT_PHASE_UNSPECIFIED", "CONTENT_PHASE_CREATING", "CONTENT_PHASE_INITIALIZING", 4 more]]

phase is the current phase of the environment content

One of the following:
"CONTENT_PHASE_UNSPECIFIED"
"CONTENT_PHASE_CREATING"
"CONTENT_PHASE_INITIALIZING"
"CONTENT_PHASE_READY"
"CONTENT_PHASE_UPDATING"
"CONTENT_PHASE_FAILED"
"CONTENT_PHASE_UNAVAILABLE"
session: Optional[str]

session is the session that is currently active in the environment.

warning_message: Optional[str]

warning_message contains warnings, e.g. when the content is present but not in the expected state.

devcontainer: Optional[Devcontainer]

devcontainer contains the status of the devcontainer.

container_id: Optional[str]

container_id is the ID of the container.

container_name: Optional[str]

container_name is the name of the container that is used to connect to the devcontainer

devcontainerconfig_in_sync: Optional[bool]

devcontainerconfig_in_sync indicates if the devcontainer is up to date w.r.t. the devcontainer config file.

devcontainer_file_path: Optional[str]

devcontainer_file_path is the path to the devcontainer file relative to the repo root

devcontainer_file_presence: Optional[Literal["PRESENCE_UNSPECIFIED", "PRESENCE_GENERATED", "PRESENCE_DISCOVERED", "PRESENCE_SPECIFIED"]]

devcontainer_file_presence indicates how the devcontainer file is present in the repo.

One of the following:
"PRESENCE_UNSPECIFIED"
"PRESENCE_GENERATED"
"PRESENCE_DISCOVERED"
"PRESENCE_SPECIFIED"
failure_message: Optional[str]

failure_message contains the reason the devcontainer failed to operate.

phase: Optional[Literal["PHASE_UNSPECIFIED", "PHASE_CREATING", "PHASE_RUNNING", 2 more]]

phase is the current phase of the devcontainer

One of the following:
"PHASE_UNSPECIFIED"
"PHASE_CREATING"
"PHASE_RUNNING"
"PHASE_STOPPED"
"PHASE_FAILED"
remote_user: Optional[str]

remote_user is the user that is used to connect to the devcontainer

remote_workspace_folder: Optional[str]

remote_workspace_folder is the folder that is used to connect to the devcontainer

secrets_in_sync: Optional[bool]

secrets_in_sync indicates if the secrets are up to date w.r.t. the running devcontainer.

session: Optional[str]

session is the session that is currently active in the devcontainer.

warning_message: Optional[str]

warning_message contains warnings, e.g. when the devcontainer is present but not in the expected state.

environment_urls: Optional[EnvironmentURLs]

environment_url contains the URL at which the environment can be accessed. This field is only set if the environment is running.

logs: Optional[str]

logs is the URL at which the environment logs can be accessed.

ops: Optional[str]

ops is the URL at which the environment ops service can be accessed.

ports: Optional[List[EnvironmentURLsPort]]
port: Optional[int]

port is the port number of the environment port

formatint32
maximum65535
minimum1024
url: Optional[str]

url is the URL at which the environment port can be accessed

ssh: Optional[EnvironmentURLsSSH]

SSH is the URL at which the environment can be accessed via SSH.

url: Optional[str]
support_bundle: Optional[str]

support_bundle is the URL at which the environment support bundle can be accessed.

failure_message: Optional[List[str]]

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[Machine]

machine contains the status of the environment machine

failure_message: Optional[str]

failure_message contains the reason the machine failed to operate.

phase: Optional[Literal["PHASE_UNSPECIFIED", "PHASE_CREATING", "PHASE_STARTING", 5 more]]

phase is the current phase of the environment machine

One of the following:
"PHASE_UNSPECIFIED"
"PHASE_CREATING"
"PHASE_STARTING"
"PHASE_RUNNING"
"PHASE_STOPPING"
"PHASE_STOPPED"
"PHASE_DELETING"
"PHASE_DELETED"
session: Optional[str]

session is the session that is currently active in the machine.

timeout: Optional[str]

timeout contains the reason the environment has timed out. If this field is empty, the environment has not timed out.

versions: Optional[MachineVersions]

versions contains the versions of components in the machine.

ami_id: Optional[str]
supervisor_commit: Optional[str]
supervisor_version: Optional[str]
warning_message: Optional[str]

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

One of the following:
"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"
runner_ack: Optional[RunnerAck]

runner_ack contains the acknowledgement from the runner that is has received the environment spec.

message: Optional[str]
spec_version: Optional[str]
status_code: Optional[Literal["STATUS_CODE_UNSPECIFIED", "STATUS_CODE_OK", "STATUS_CODE_INVALID_RESOURCE", "STATUS_CODE_FAILED_PRECONDITION"]]
One of the following:
"STATUS_CODE_UNSPECIFIED"
"STATUS_CODE_OK"
"STATUS_CODE_INVALID_RESOURCE"
"STATUS_CODE_FAILED_PRECONDITION"
secrets: Optional[List[Secret]]

secrets contains the status of the environment secrets

id: Optional[str]

id is the unique identifier of the secret.

failure_message: Optional[str]

failure_message contains the reason the secret failed to be materialize.

phase: Optional[Literal["CONTENT_PHASE_UNSPECIFIED", "CONTENT_PHASE_CREATING", "CONTENT_PHASE_INITIALIZING", 4 more]]
One of the following:
"CONTENT_PHASE_UNSPECIFIED"
"CONTENT_PHASE_CREATING"
"CONTENT_PHASE_INITIALIZING"
"CONTENT_PHASE_READY"
"CONTENT_PHASE_UPDATING"
"CONTENT_PHASE_FAILED"
"CONTENT_PHASE_UNAVAILABLE"
secret_name: Optional[str]
session: Optional[str]

session is the session that is currently active in the environment.

warning_message: Optional[str]

warning_message contains warnings, e.g. when the secret is present but not in the expected state.

ssh_public_keys: Optional[List[SSHPublicKey]]

ssh_public_keys contains the status of the environment ssh public keys

id: Optional[str]

id is the unique identifier of the public key

phase: Optional[Literal["CONTENT_PHASE_UNSPECIFIED", "CONTENT_PHASE_CREATING", "CONTENT_PHASE_INITIALIZING", 4 more]]

phase is the current phase of the public key

One of the following:
"CONTENT_PHASE_UNSPECIFIED"
"CONTENT_PHASE_CREATING"
"CONTENT_PHASE_INITIALIZING"
"CONTENT_PHASE_READY"
"CONTENT_PHASE_UPDATING"
"CONTENT_PHASE_FAILED"
"CONTENT_PHASE_UNAVAILABLE"
status_version: Optional[str]

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.

warning_message: Optional[List[str]]

warning_message contains warnings, e.g. when the environment is present but not in the expected state.

CreateEnvironmentFromProject

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
response = client.environments.create_from_project(
    project_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047",
    spec={
        "machine": {
            "class": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
        },
        "timeout": {
            "disconnected": "14400s"
        },
    },
)
print(response.environment)
{
  "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"
      ]
    }
  }
}
Returns Examples
{
  "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"
      ]
    }
  }
}