> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Environment From Project

> Creates an environment from an existing project configuration and starts it.

`Unary` · [`Environments`](/docs/api-reference/generated/environment/overview)

Creates an environment from an existing project configuration and starts it.

This method uses project settings as defaults but allows overriding specific
configurations. Project settings take precedence over default configurations,
while custom specifications in the request override project settings.

### Examples

* Create with project defaults:

  Creates an environment using all default settings from the project configuration.

  ```yaml theme={null}
  projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  ```

* Create with custom compute resources:

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

  ```yaml theme={null}
  projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  spec:
    machine:
      class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
    timeout:
      disconnected: "14400s"  # 4 hours in seconds
  ```

## Endpoint

```text theme={null}
POST /api/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject
```

Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.

## Request example

<CodeGroup>
  ```bash cURL theme={null}
  export ONA_HOST=https://app.ona.com
  export ONA_API_KEY=<your-token>

  curl --request POST \
    --url "$ONA_HOST/api/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject" \
    --header "Authorization: Bearer $ONA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "projectId": "<project-id>"
  }'
  ```

  ```python Python theme={null}
  import gitpod.v1.environment_pb2 as environment_pb2
  from ona_sdk import create_client_from_env

  ona = create_client_from_env()
  request = environment_pb2.CreateEnvironmentFromProjectRequest(
      project_id="<project-id>",
  )
  response = ona.services.environment.create_environment_from_project(request)
  print(response)
  ```

  ```typescript TypeScript theme={null}
  import { create } from "@bufbuild/protobuf";
  import { createClientFromEnv } from "@gitpod/sdk";
  import { CreateEnvironmentFromProjectRequestSchema } from "@gitpod/sdk/gitpod/v1/environment_pb";

  async function main() {
    const ona = createClientFromEnv();
    const request = create(CreateEnvironmentFromProjectRequestSchema, {
      projectId: "<project-id>",
    });
    const response = await ona.services.environment.createEnvironmentFromProject(request);
    console.log(response);
  }

  main().catch(console.error);
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"log"

  	"connectrpc.com/connect"
  	"github.com/gitpod-io/gitpod-sdk-go/sdk"
  	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
  )

  func main() {
  	ona, err := sdk.NewFromEnv()
  	if err != nil {
  		log.Fatal(err)
  	}

  	request := connect.NewRequest(&gitpodpb.CreateEnvironmentFromProjectRequest{
  		ProjectId: "<project-id>",
  	})
  	response, err := ona.Services.Environment.CreateEnvironmentFromProject(context.Background(), request)
  	if err != nil {
  		log.Fatal(err)
  	}
  	fmt.Println(response.Msg)
  }
  ```

  ```json Request body theme={null}
  {
    "projectId": "<project-id>"
  }
  ```
</CodeGroup>

## Request

`gitpod.v1.CreateEnvironmentFromProjectRequest`

| Field         | Type                                                | Required | Description                                                                                                                                                                               |
| ------------- | --------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`   | string                                              | No       | Constraints: `string.uuid=true`.                                                                                                                                                          |
| `spec`        | [EnvironmentSpec](#type-gitpod-v1-environment-spec) | No       | 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 |
| `name`        | string                                              | No       | name is a user-defined identifier for the environment. If not specified, the system will generate a name. Constraints: `string.max_len=80`.                                               |
| `annotations` | map of string to string                             | No       | annotations are key/value pairs attached to the environment metadata.                                                                                                                     |
| `sessionId`   | string                                              | No       | session\_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly. Constraints: `ignore=1, string.uuid=true`.                               |

## Response

`gitpod.v1.CreateEnvironmentFromProjectResponse`

| Field         | Type                                       | Required | Description                   |
| ------------- | ------------------------------------------ | -------- | ----------------------------- |
| `environment` | [Environment](#type-gitpod-v1-environment) | Yes      | Constraints: `required=true`. |

## Related types

<a id="type-gitpod-v1-environment" />

<Accordion title="Environment">
  `gitpod.v1.Environment`

  | Field      | Type                                                        | Required | Description                                                                                                                        |
  | ---------- | ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
  | `id`       | string                                                      | No       | ID is a unique identifier of this environment. No other environment with the same name must be managed by this environment manager |
  | `metadata` | [EnvironmentMetadata](#type-gitpod-v1-environment-metadata) | No       | Metadata is data associated with this environment that's required for other parts of Gitpod to function                            |
  | `spec`     | [EnvironmentSpec](#type-gitpod-v1-environment-spec)         | No       | Spec is the configuration of the environment that's required for the runner to start the environment                               |
  | `status`   | [EnvironmentStatus](#type-gitpod-v1-environment-status)     | No       | Status is the current status of the environment                                                                                    |
</Accordion>

<a id="type-gitpod-v1-environment-metadata" />

<Accordion title="EnvironmentMetadata">
  EnvironmentMetadata is data associated with an environment that's required for
  other parts of the system to function

  `gitpod.v1.EnvironmentMetadata`

  | Field                | Type                                                | Required | Description                                                                                                                                                               |
  | -------------------- | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `organizationId`     | string                                              | No       | organization\_id is the ID of the organization that contains the environment Constraints: `string.uuid=true`.                                                             |
  | `annotations`        | map of string to string                             | No       | annotations are key/value pairs that gets attached to the environment.                                                                                                    |
  | `name`               | string                                              | No       | name is the name of the environment as specified by the user Constraints: `string.max_len=80`.                                                                            |
  | `creator`            | Subject                                             | No       | creator is the identity of the creator of the environment                                                                                                                 |
  | `originalContextUrl` | string                                              | No       | original\_context\_url is the normalized URL from which the environment was created                                                                                       |
  | `createdAt`          | RFC 3339 timestamp                                  | No       | Time when the Environment was created.                                                                                                                                    |
  | `projectId`          | string                                              | No       | If the Environment was started from a project, the project\_id will reference the project.                                                                                |
  | `runnerId`           | string                                              | No       | Runner is the ID of the runner that runs this environment.                                                                                                                |
  | `lastStartedAt`      | RFC 3339 timestamp                                  | No       | Time when the Environment was last started (i.e. CreateEnvironment or StartEnvironment were called).                                                                      |
  | `archivedAt`         | RFC 3339 timestamp                                  | No       | Time when the Environment was archived. If not set, the environment is not archived.                                                                                      |
  | `role`               | [EnvironmentRole](#enum-gitpod-v1-environment-role) | No       | role is the role of the environment                                                                                                                                       |
  | `prebuildId`         | string                                              | No       | prebuild\_id is the ID of the prebuild this environment was created from. Only set if the environment was created from a prebuild. Constraints: `string.uuid=true`.       |
  | `lockdownAt`         | RFC 3339 timestamp                                  | No       | 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. |
  | `sessionId`          | string                                              | No       | session\_id is the ID of the session this environment belongs to.                                                                                                         |
</Accordion>

<a id="type-gitpod-v1-environment-spec" />

<Accordion title="EnvironmentSpec">
  EnvironmentSpec specifies the configuration of an environment for an environment
  start

  `gitpod.v1.EnvironmentSpec`

  | Field                  | Type                                                                          | Required | Description                                                                                                                                                                                                                         |
  | ---------------------- | ----------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `specVersion`          | 64-bit integer string                                                         | No       | 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. |
  | `desiredPhase`         | [EnvironmentPhase](#enum-gitpod-v1-environment-phase)                         | No       | Phase is the desired phase of the environment                                                                                                                                                                                       |
  | `machine`              | [Machine](#type-gitpod-v1-environment-spec-machine)                           | No       | machine is the machine spec of the environment                                                                                                                                                                                      |
  | `content`              | [Content](#type-gitpod-v1-environment-spec-content)                           | No       | content is the content spec of the environment                                                                                                                                                                                      |
  | `secrets`              | array of [Secret](#type-gitpod-v1-environment-spec-secret)                    | No       | secrets are confidential data that is mounted into the environment                                                                                                                                                                  |
  | `ports`                | array of [EnvironmentPort](#type-gitpod-v1-environment-spec-environment-port) | No       | ports is the set of ports which ought to be exposed to your network                                                                                                                                                                 |
  | `timeout`              | [Timeout](#type-gitpod-v1-environment-spec-timeout)                           | No       | Timeout configures the environment timeout                                                                                                                                                                                          |
  | `admission`            | [AdmissionLevel](#enum-gitpod-v1-admission-level)                             | No       | admission controlls who can access the environment and its ports.                                                                                                                                                                   |
  | `devcontainer`         | [DevContainer](#type-gitpod-v1-environment-spec-dev-container)                | No       | devcontainer is the devcontainer spec of the environment                                                                                                                                                                            |
  | `sshPublicKeys`        | array of [SSHPublicKey](#type-gitpod-v1-environment-spec-ssh-public-key)      | No       | ssh\_public\_keys are the public keys used to ssh into the environment                                                                                                                                                              |
  | `automationsFile`      | [AutomationsFile](#type-gitpod-v1-environment-spec-automations-file)          | No       | automations\_file is the automations file spec of the environment                                                                                                                                                                   |
  | `workflowActionId`     | string                                                                        | No       | workflow\_action\_id is an optional reference to the workflow execution action that created this environment. Used for tracking and event correlation. Constraints: `string.uuid=true`.                                             |
  | `kernelControlsConfig` | [KernelControlsConfig](#type-gitpod-v1-kernel-controls-config)                | No       | kernel\_controls\_config configures kernel-level controls for this environment                                                                                                                                                      |
  | `securityPolicyId`     | string                                                                        | No       | security\_policy\_id references the security policy used for this environment. If empty, the environment has no security policy. Constraints: `ignore=1, string.uuid=true`.                                                         |
</Accordion>

<a id="type-gitpod-v1-environment-spec-automations-file" />

<Accordion title="AutomationsFile">
  `gitpod.v1.EnvironmentSpec.AutomationsFile`

  | Field                 | Type                       | Required | Description                                                                                                                                                                                                                                                         |
  | --------------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `session`             | string                     | No       |                                                                                                                                                                                                                                                                     |
  | `automationsFilePath` | string                     | No       | automations\_file\_path is the path to the automations file that is applied in the environment, relative to the repo root. Constraints: `cel.expression=this.matches('^$\|^[^/].*'), cel.id=relative_path, cel.message=path must not be absolute (start with a /)`. |
  | `triggerFilter`       | array of AutomationTrigger | No       | 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.                                                                               |
</Accordion>

<a id="type-gitpod-v1-environment-spec-content" />

<Accordion title="Content">
  `gitpod.v1.EnvironmentSpec.Content`

  | Field         | Type                   | Required | Description                                                     |
  | ------------- | ---------------------- | -------- | --------------------------------------------------------------- |
  | `session`     | string                 | No       |                                                                 |
  | `initializer` | EnvironmentInitializer | No       | initializer configures how the environment is to be initialized |
  | `gitUsername` | string                 | No       | The Git username                                                |
  | `gitEmail`    | string                 | No       | The Git email address                                           |
</Accordion>

<a id="type-gitpod-v1-environment-spec-dev-container" />

<Accordion title="DevContainer">
  `gitpod.v1.EnvironmentSpec.DevContainer`

  | Field                      | Type                                                                             | Required | Description                                                                                                                                                                                                                      |
  | -------------------------- | -------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `session`                  | string                                                                           | No       |                                                                                                                                                                                                                                  |
  | `devcontainerFilePath`     | string                                                                           | No       | devcontainer\_file\_path is the path to the devcontainer file relative to the repo root Constraints: `cel.expression=this.matches('^$\|^[^/].*'), cel.id=relative_path, cel.message=path must not be absolute (start with a /)`. |
  | `dotfiles`                 | Dotfiles                                                                         | No       | Experimental: dotfiles is the dotfiles configuration of the devcontainer                                                                                                                                                         |
  | `defaultDevcontainerImage` | string                                                                           | No       | default\_devcontainer\_image is the default image that is used to start the devcontainer if no devcontainer config file is found                                                                                                 |
  | `lifecycleStage`           | [LifecycleStage](#enum-gitpod-v1-environment-spec-dev-container-lifecycle-stage) | No       | lifecycle\_stage controls which devcontainer lifecycle commands are executed. Defaults to FULL if not specified. Constraints: `enum.defined_only=true`.                                                                          |
</Accordion>

<a id="type-gitpod-v1-environment-spec-environment-port" />

<Accordion title="EnvironmentPort">
  `gitpod.v1.EnvironmentSpec.EnvironmentPort`

  | Field       | Type                                                                   | Required | Description                                                                                                                                                                                                            |
  | ----------- | ---------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `port`      | integer                                                                | No       | port number Constraints: `int32.gte=1024, int32.lte=65535`.                                                                                                                                                            |
  | `admission` | [AdmissionLevel](#enum-gitpod-v1-admission-level)                      | No       | policy of this port                                                                                                                                                                                                    |
  | `name`      | string                                                                 | No       | name of this port Constraints: `string.max_len=100, string.min_len=1`.                                                                                                                                                 |
  | `protocol`  | [Protocol](#enum-gitpod-v1-environment-spec-environment-port-protocol) | No       | protocol for communication (Gateway proxy → user environment service). this setting only affects the protocol used between Gateway and user environment services.                                                      |
  | `authNonce` | 64-bit integer string                                                  | No       | auth\_nonce is a monotonically increasing counter incremented by the backend whenever the port's admission level changes. Used by the proxy to invalidate browser auth cookies without requiring a backend round-trip. |
</Accordion>

<a id="type-gitpod-v1-environment-spec-machine" />

<Accordion title="Machine">
  `gitpod.v1.EnvironmentSpec.Machine`

  | Field            | Type    | Required | Description                                                                                                                                                                                       |
  | ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `session`        | string  | No       |                                                                                                                                                                                                   |
  | `class`          | string  | No       | Class denotes the class of the environment we ought to start                                                                                                                                      |
  | `preferDualDisk` | boolean | No       | prefer\_dual\_disk indicates the management plane wants this environment to use a dual-disk layout (separate system and data disks). The runner may ignore this if it does not support dual-disk. |
</Accordion>

<a id="type-gitpod-v1-environment-spec-ssh-public-key" />

<Accordion title="SSHPublicKey">
  `gitpod.v1.EnvironmentSpec.SSHPublicKey`

  | Field   | Type   | Required | Description                                                  |
  | ------- | ------ | -------- | ------------------------------------------------------------ |
  | `id`    | string | No       | id is the unique identifier of the public key                |
  | `value` | string | No       | value is the actual public key in the public key file format |
</Accordion>

<a id="type-gitpod-v1-environment-spec-secret" />

<Accordion title="Secret">
  `gitpod.v1.EnvironmentSpec.Secret`

  | Field                            | Type                                                   | Required       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | -------------------------------- | ------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `name`                           | string                                                 | No             | name is the human readable description of the secret                                                                                                                                                                                                                                                                                                                                                                                           |
  | `source`                         | string                                                 | No             | source is the source of the secret, for now control-plane or runner                                                                                                                                                                                                                                                                                                                                                                            |
  | `sourceRef`                      | string                                                 | No             | source\_ref into the source, in case of control-plane this is uuid of the secret                                                                                                                                                                                                                                                                                                                                                               |
  | `filePath`                       | string                                                 | One of `mount` | file\_path is the path inside the devcontainer where the secret is mounted                                                                                                                                                                                                                                                                                                                                                                     |
  | `environmentVariable`            | string                                                 | One of `mount` |                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | `gitCredentialHost`              | string                                                 | One of `mount` |                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  | `containerRegistryBasicAuthHost` | string                                                 | One of `mount` | container\_registry\_basic\_auth\_host is the hostname of the container registry that supports basic auth                                                                                                                                                                                                                                                                                                                                      |
  | `apiOnly`                        | boolean                                                | One of `mount` | api\_only indicates the secret is only available via API/CLI. These secrets are resolved but NOT automatically injected into services or devcontainers.                                                                                                                                                                                                                                                                                        |
  | `session`                        | string                                                 | No             | session indicated the current session of the secret. When the session does not change, secrets are not reloaded in the environment.                                                                                                                                                                                                                                                                                                            |
  | `id`                             | string                                                 | No             | id is the unique identifier of the secret.                                                                                                                                                                                                                                                                                                                                                                                                     |
  | `scope`                          | [Scope](#enum-gitpod-v1-environment-spec-secret-scope) | No             | scope indicates where this secret originated from. Used to filter secrets during build (only org and project secrets are injected).                                                                                                                                                                                                                                                                                                            |
  | `credentialProxy`                | CredentialProxy                                        | No             | 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. |
  | `sourceDetails`                  | Source                                                 | No             | source\_details contains the typed source configuration for management-plane secrets.                                                                                                                                                                                                                                                                                                                                                          |
</Accordion>

<a id="type-gitpod-v1-environment-spec-timeout" />

<Accordion title="Timeout">
  Timeout configures the environment timeout

  `gitpod.v1.EnvironmentSpec.Timeout`

  | Field          | Type            | Required | Description                                                                                                                                                                                                                                                                                                                                  |
  | -------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `disconnected` | duration string | No       | inacitivity is the maximum time of disconnection before the environment is stopped or paused. Minimum duration is 30 minutes. Set to 0 to disable. Constraints: `cel.expression=this == duration('0s') \|\| this >= duration('1800s'), cel.id=disconnected_timeout, cel.message=value must be 0s (disabled) or at least 1800s (30 minutes)`. |
</Accordion>

<a id="type-gitpod-v1-environment-status" />

<Accordion title="EnvironmentStatus">
  EnvironmentStatus describes an environment status

  `gitpod.v1.EnvironmentStatus`

  | Field             | Type                                                  | Required | Description                                                                                                                                                                                                                                                                                                                                   |
  | ----------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `statusVersion`   | 64-bit integer string                                 | No       | 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. |
  | `runnerAck`       | RunnerACK                                             | No       | runner\_ack contains the acknowledgement from the runner that is has received the environment spec.                                                                                                                                                                                                                                           |
  | `phase`           | [EnvironmentPhase](#enum-gitpod-v1-environment-phase) | No       | the phase of an environment is a simple, high-level summary of where the environment is in its lifecycle                                                                                                                                                                                                                                      |
  | `failureMessage`  | array of string                                       | No       | 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.                                                                                                                                                                  |
  | `environmentUrls` | EnvironmentURLs                                       | No       | environment\_url contains the URL at which the environment can be accessed. This field is only set if the environment is running.                                                                                                                                                                                                             |
  | `machine`         | Machine                                               | No       | machine contains the status of the environment machine                                                                                                                                                                                                                                                                                        |
  | `secrets`         | array of Secret                                       | No       | secrets contains the status of the environment secrets                                                                                                                                                                                                                                                                                        |
  | `content`         | Content                                               | No       | content contains the status of the environment content.                                                                                                                                                                                                                                                                                       |
  | `devcontainer`    | DevContainer                                          | No       | devcontainer contains the status of the devcontainer.                                                                                                                                                                                                                                                                                         |
  | `sshPublicKeys`   | array of SSHPublicKey                                 | No       | ssh\_public\_keys contains the status of the environment ssh public keys                                                                                                                                                                                                                                                                      |
  | `warningMessage`  | array of string                                       | No       | warning\_message contains warnings, e.g. when the environment is present but not in the expected state.                                                                                                                                                                                                                                       |
  | `automationsFile` | AutomationsFile                                       | No       | automations\_file contains the status of the automations file.                                                                                                                                                                                                                                                                                |
  | `activitySignal`  | EnvironmentActivitySignal                             | No       | activity\_signal is the last activity signal for the environment.                                                                                                                                                                                                                                                                             |
</Accordion>

<a id="type-gitpod-v1-kernel-controls-config" />

<Accordion title="KernelControlsConfig">
  KernelControlsConfig configures kernel-level controls for the environment

  `gitpod.v1.KernelControlsConfig`

  | Field           | Type                                             | Required | Description                                                                                                      |
  | --------------- | ------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
  | `veto`          | Veto                                             | No       | veto controls blocking mechanisms                                                                                |
  | `bpfDebugLevel` | [BPFDebugLevel](#enum-gitpod-v1-bpf-debug-level) | No       | bpf\_debug\_level controls the verbosity of BPF trace\_pipe output for all BPF-based agents in this environment. |
</Accordion>

<a id="enum-gitpod-v1-admission-level" />

<Accordion title="AdmissionLevel">
  Admission level describes who can access an environment instance and its ports.

  | Value                          | Number | Description                                                                                                                                                       |
  | ------------------------------ | -----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `ADMISSION_LEVEL_UNSPECIFIED`  |      0 |                                                                                                                                                                   |
  | `ADMISSION_LEVEL_OWNER_ONLY`   |      1 | **Deprecated.** ADMISSION\_LEVEL\_OWNER\_ONLY means the environment can only be accessed by the creator. Deprecated: Use ADMISSION\_LEVEL\_CREATOR\_ONLY instead. |
  | `ADMISSION_LEVEL_EVERYONE`     |      2 | ADMISSION\_LEVEL\_EVERYONE means the environment (including ports) can be accessed by everyone.                                                                   |
  | `ADMISSION_LEVEL_ORGANIZATION` |      3 | ADMISSION\_LEVEL\_ORGANIZATION means the environment (including ports) can be accessed by all members of the organization.                                        |
  | `ADMISSION_LEVEL_CREATOR_ONLY` |      4 | ADMISSION\_LEVEL\_CREATOR\_ONLY means the environment (including ports) can only be accessed by the user who created the environment.                             |
</Accordion>

<a id="enum-gitpod-v1-bpf-debug-level" />

<Accordion title="BPFDebugLevel">
  BPFDebugLevel controls the verbosity of BPF trace\_pipe output (bpf\_printk).
  Applies to all BPF-based agents (veto exec, future agents).

  | Value                         | Number | Description                                                                     |
  | ----------------------------- | -----: | ------------------------------------------------------------------------------- |
  | `BPF_DEBUG_LEVEL_UNSPECIFIED` |      0 | BPF\_DEBUG\_LEVEL\_UNSPECIFIED disables all bpf\_printk output (default).       |
  | `BPF_DEBUG_LEVEL_INFO`        |      1 | BPF\_DEBUG\_LEVEL\_INFO enables decision-level prints (e.g., veto allow/block). |
  | `BPF_DEBUG_LEVEL_VERBOSE`     |      2 | BPF\_DEBUG\_LEVEL\_VERBOSE enables all debug prints including data fillers.     |
</Accordion>

<a id="enum-gitpod-v1-environment-phase" />

<Accordion title="EnvironmentPhase">
  | Value                           | Number | Description                                                                                                                                                                                                               |
  | ------------------------------- | -----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `ENVIRONMENT_PHASE_UNSPECIFIED` |      0 | Unknown indicates an issue within the environment manager in that it cannot determine the actual phase of an environment. This phase is usually accompanied by an error.                                                  |
  | `ENVIRONMENT_PHASE_CREATING`    |     10 | Creating means that the environment is first created. We organise the SCM credentials, parse context URL if need be, and allocate the unit of compute.                                                                    |
  | `ENVIRONMENT_PHASE_STARTING`    |     20 | Starting means that the environment is currently being started. This includes starting the unit of compute (machine), resolving secrets, setting up the Git config, initiaing the content, and starting the devcontainer. |
  | `ENVIRONMENT_PHASE_RUNNING`     |     40 | Running means the environment is able to actively perform work, either by serving a user through Theia, or as a headless environment.                                                                                     |
  | `ENVIRONMENT_PHASE_UPDATING`    |     45 | Updating means the environment is currently being updated. This includes content updates, devcontainer updates, secret updates and SSH public key updates. This phase implies that the environment is running.            |
  | `ENVIRONMENT_PHASE_STOPPING`    |     50 | Stopping means that the environment is currently shutting down. It could go to stopped every moment.                                                                                                                      |
  | `ENVIRONMENT_PHASE_STOPPED`     |     60 | Stopped means the environment ended regularly because it was shut down.                                                                                                                                                   |
  | `ENVIRONMENT_PHASE_DELETING`    |     70 | Deleting means the environment is currently being deleted. It could go to deleted any moment. This phase implies that the environment is stopped.                                                                         |
  | `ENVIRONMENT_PHASE_DELETED`     |     80 | Deleted means the environment was deleted and cannot be started again. This phase implies that the environment is stopped.                                                                                                |
</Accordion>

<a id="enum-gitpod-v1-environment-role" />

<Accordion title="EnvironmentRole">
  EnvironmentRole represents the role of an environment

  | Value                          | Number | Description                                                |
  | ------------------------------ | -----: | ---------------------------------------------------------- |
  | `ENVIRONMENT_ROLE_UNSPECIFIED` |      0 |                                                            |
  | `ENVIRONMENT_ROLE_DEFAULT`     |      1 | Default role for environments                              |
  | `ENVIRONMENT_ROLE_PREBUILD`    |      2 | Prebuild role for environments that are prebuilds          |
  | `ENVIRONMENT_ROLE_WORKFLOW`    |      3 | Workflow role for environments that are part of a workflow |
</Accordion>

<a id="enum-gitpod-v1-environment-spec-dev-container-lifecycle-stage" />

<Accordion title="LifecycleStage">
  LifecycleStage controls which devcontainer lifecycle commands are executed.
  See [https://containers.dev/implementors/json\_reference/#lifecycle-scripts](https://containers.dev/implementors/json_reference/#lifecycle-scripts)

  | Value                         | Number | Description                                                                                                                                                                                                                                                                           |
  | ----------------------------- | -----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `LIFECYCLE_STAGE_UNSPECIFIED` |      0 | LIFECYCLE\_STAGE\_UNSPECIFIED defaults to FULL for backward compatibility                                                                                                                                                                                                             |
  | `LIFECYCLE_STAGE_FULL`        |      1 | LIFECYCLE\_STAGE\_FULL runs all devcontainer lifecycle commands (default): initializeCommand, onCreateCommand, updateContentCommand, postCreateCommand, postStartCommand, and postAttachCommand.                                                                                      |
  | `LIFECYCLE_STAGE_PREBUILD`    |      2 | LIFECYCLE\_STAGE\_PREBUILD runs only the lifecycle commands suitable for prebuilding: initializeCommand, onCreateCommand, and updateContentCommand. Skips postCreateCommand, postStartCommand, and postAttachCommand which are intended to run when a user connects to the container. |
</Accordion>

<a id="enum-gitpod-v1-environment-spec-environment-port-protocol" />

<Accordion title="Protocol">
  Protocol describes the communication protocol between Gateway and user environment services.

  | Value                  | Number | Description |
  | ---------------------- | -----: | ----------- |
  | `PROTOCOL_UNSPECIFIED` |      0 |             |
  | `PROTOCOL_HTTP`        |      1 |             |
  | `PROTOCOL_HTTPS`       |      2 |             |
</Accordion>

<a id="enum-gitpod-v1-environment-spec-secret-scope" />

<Accordion title="Scope">
  Scope indicates the origin of the secret for filtering purposes.

  | Value                   | Number | Description |
  | ----------------------- | -----: | ----------- |
  | `SCOPE_UNSPECIFIED`     |      0 |             |
  | `SCOPE_ORGANIZATION`    |      1 |             |
  | `SCOPE_PROJECT`         |      2 |             |
  | `SCOPE_USER`            |      3 |             |
  | `SCOPE_SERVICE_ACCOUNT` |      4 |             |
  | `SCOPE_RUNNER`          |      5 |             |
</Accordion>