### Preview Server Setup

Source: https://ona.com/docs/ona/configuration/tasks-and-services/examples

Starts a preview server to serve a built application. Use this for testing frontend applications locally.

```yaml
services:
  preview:
    name: Preview server
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: |
        npm install
        npm run build
        npx serve -p 3000 ./build
      ready: curl -sf http://localhost:3000 > /dev/null
```

--------------------------------

### Start Service API Request

Source: https://ona.com/docs/api-reference/resources/environments/subresources/automations/subresources/services/methods/start

Example cURL request and response for starting a service.

```bash
curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/StartService \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

```json
{}
```

--------------------------------

### Start agent execution via cURL

Source: https://ona.com/docs/api-reference/resources/agents/methods/start_execution

Request example for the StartAgent endpoint using cURL.

```bash
curl https://app.gitpod.io/api/gitpod.v1.AgentService/StartAgent \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

--------------------------------

### Initialize Terraform Module

Source: https://ona.com/docs/ona/runners/gcp/setup

Clone the Terraform module repository, copy the example configuration, and initialize Terraform. Ensure you have Terraform >= 1.3 and GCP CLI installed and authenticated.

```bash
# Clone the Terraform module repository
git clone <repository-url>
cd gitpod-gcp-terraform

# Copy the example configuration
cp terraform.tfvars.example terraform.tfvars

# Initialize Terraform
terraform init
```

--------------------------------

### Start task execution via cURL

Source: https://ona.com/docs/api-reference/resources/environments/subresources/automations/subresources/tasks/methods/start

Example request to start a task using the Gitpod API.

```bash
curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/StartTask \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

--------------------------------

### Start Prototype Preview Server

Source: https://ona.com/docs/ona/workflows

After prototyping a UI from a screenshot, use this prompt to have Ona start a preview server and provide the URL for viewing the prototype.

```text
Start a preview server and give me the URL to view the prototype.
```

--------------------------------

### Get Environment Class cURL Example

Source: https://ona.com/docs/api-reference/resources/runners/subresources/configurations/subresources/environment_classes/methods/retrieve

Example cURL request to retrieve details about a specific environment class.

```bash
curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/GetEnvironmentClass \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

--------------------------------

### Create Environment Examples

Source: https://ona.com/docs/api-reference/resources/environments/methods/mark_active

Examples for creating development environments using context URLs, specific Git branches, or custom resource configurations.

```yaml
spec:
  machine:
    class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  content:
    initializer:
      specs:
        - contextUrl:
            url: "https://github.com/gitpod-io/gitpod"
```

```yaml
spec:
  machine:
    class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  content:
    initializer:
      specs:
        - git:
            remoteUri: "https://github.com/gitpod-io/gitpod"
            cloneTarget: "main"
            targetMode: "CLONE_TARGET_MODE_REMOTE_BRANCH"
```

```yaml
spec:
  machine:
    class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  content:
    initializer:
      specs:
        - contextUrl:
            url: "https://github.com/gitpod-io/gitpod"
  timeout:
    disconnected: "7200s"  # 2 hours in seconds
  ports:
    - port: 3000
      admission: "ADMISSION_LEVEL_EVERYONE"
      name: "Web App"
```

--------------------------------

### Get Secret Value cURL Example

Source: https://ona.com/docs/api-reference/resources/secrets/methods/get_value

Example cURL command to retrieve a secret value. Replace `$GITPOD_API_KEY` with your actual API key.

```bash
curl https://app.gitpod.io/api/gitpod.v1.SecretService/GetSecretValue \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

```

--------------------------------

### Full Workflow Example

Source: https://ona.com/docs/ona/environments/agent-environments

An end-to-end bash script demonstrating environment creation, command execution, and cleanup. It uses `--dont-wait` for immediate ID retrieval and polls for readiness.

```bash
#!/bin/bash
set -euo pipefail

# Create environment from a project, wait for it to start
ENV_ID=$(ona environment create <project-id> --dont-wait)
echo "Created environment: $ENV_ID"

# Wait for the environment to be running
ona environment start "$ENV_ID"

# Run commands
ona environment exec "$ENV_ID" -- npm install
ona environment exec "$ENV_ID" --timeout 300 -- npm test

# Clean up
ona environment delete "$ENV_ID"
echo "Done"
```

--------------------------------

### Create Project

Source: https://ona.com/docs/api-reference/resources/projects/methods/create_from_environment

Creates a new project with specified configuration. Use this method to set up development projects, configure environments, define settings, and initialize content.

```go
post/gitpod.v1.ProjectService/CreateProject
```

--------------------------------

### Get SSO Login URL cURL Example

Source: https://ona.com/docs/api-reference/resources/accounts/methods/get_sso_login_url

Example cURL command to fetch the SSO login URL. Requires Content-Type and Authorization headers.

```bash
curl https://app.gitpod.io/api/gitpod.v1.AccountService/GetSSOLoginURL \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{ 
          "email": "user@company.com"
        }'
```

--------------------------------

### Create Prebuild Response Example

Source: https://ona.com/docs/api-reference/resources/prebuilds/methods/create

Example JSON response for a successful prebuild creation, detailing metadata, spec, and status.

```json
{
  "prebuild": {
    "metadata": {
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "executor": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "triggeredBy": "PREBUILD_TRIGGER_UNSPECIFIED"
    },
    "spec": {
      "desiredPhase": "PREBUILD_PHASE_UNSPECIFIED",
      "specVersion": "specVersion",
      "timeout": "+9125115.360s"
    },
    "status": {
      "phase": "PREBUILD_PHASE_UNSPECIFIED",
      "completionTime": "2019-12-27T18:11:19.117Z",
      "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "failureMessage": "failureMessage",
      "logUrl": "https://example.com",
      "snapshotCompletionPercentage": 100,
      "snapshotSizeBytes": "snapshotSizeBytes",
      "statusVersion": "statusVersion",
      "warningMessage": "warningMessage"
    },
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  }
}
```

--------------------------------

### Get Runner Response

Source: https://ona.com/docs/api-reference/resources/runners/methods/retrieve

Example JSON response for a GetRunner request.

```json
{
  "runner": {
    "createdAt": "2019-12-27T18:11:19.117Z",
    "creator": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "principal": "PRINCIPAL_UNSPECIFIED"
    },
    "kind": "RUNNER_KIND_UNSPECIFIED",
    "name": "name",
    "provider": "RUNNER_PROVIDER_UNSPECIFIED",
    "runnerId": "runnerId",
    "runnerManagerId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "spec": {
      "configuration": {
        "autoUpdate": true,
        "continuousProfiling": true,
        "devcontainerImageCacheEnabled": true,
        "encryptedHoneycombApiKey": "U3RhaW5sZXNzIHJvY2tz",
        "logLevel": "LOG_LEVEL_UNSPECIFIED",
        "metrics": {
          "enabled": true,
          "managedMetricsEnabled": true,
          "password": "password",
          "url": "url",
          "username": "username"
        },
        "region": "region",
        "releaseChannel": "RUNNER_RELEASE_CHANNEL_UNSPECIFIED",
        "updateWindow": {
          "endHour": 0,
          "startHour": 0
        }
      },
      "desiredPhase": "RUNNER_PHASE_UNSPECIFIED",
      "variant": "RUNNER_VARIANT_UNSPECIFIED"
    },
    "status": {
      "additionalInfo": [
        {
          "key": "key",
          "value": "value"
        }
      ],
      "capabilities": [
        "RUNNER_CAPABILITY_UNSPECIFIED"
      ],
      "gatewayInfo": {
        "gateway": {
          "name": "name",
          "url": "url",
          "region": "region"
        },
        "latency": "+9125115.360s"
      },
      "llmUrl": "llmUrl",
      "logUrl": "logUrl",
      "message": "message",
      "phase": "RUNNER_PHASE_UNSPECIFIED",
      "publicKey": "U3RhaW5sZXNzIHJvY2tz",
      "region": "region",
      "supportBundleUrl": "supportBundleUrl",
      "systemDetails": "systemDetails",
      "updatedAt": "2019-12-27T18:11:19.117Z",
      "version": "version"
    },
    "updatedAt": "2019-12-27T18:11:19.117Z"
  }
}
```

--------------------------------

### Get Membership Response

Source: https://ona.com/docs/api-reference/resources/groups/subresources/memberships/methods/retrieve

Example JSON response for a successful membership check.

```json
{
  "member": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "avatarUrl": "avatarUrl",
    "groupId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "name": "name",
    "subject": {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "principal": "PRINCIPAL_UNSPECIFIED"
    }
  }
}
```

--------------------------------

### List Prebuilds Response Example

Source: https://ona.com/docs/api-reference/resources/prebuilds/methods/list

Example JSON response when listing prebuilds, showing pagination and a list of prebuild objects.

```json
{
  "pagination": {
    "nextToken": "nextToken"
  },
  "prebuilds": [
    {
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "creator": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "executor": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "triggeredBy": "PREBUILD_TRIGGER_UNSPECIFIED"
      },
      "spec": {
        "desiredPhase": "PREBUILD_PHASE_UNSPECIFIED",
        "specVersion": "specVersion",
        "timeout": "+9125115.360s"
      },
      "status": {
        "phase": "PREBUILD_PHASE_UNSPECIFIED",
        "completionTime": "2019-12-27T18:11:19.117Z",
        "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "failureMessage": "failureMessage",
        "logUrl": "https://example.com",
        "snapshotCompletionPercentage": 100,
        "snapshotSizeBytes": "snapshotSizeBytes",
        "statusVersion": "statusVersion",
        "warningMessage": "warningMessage"
      },
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    }
  ]
}
```

--------------------------------

### Get Runner cURL Request

Source: https://ona.com/docs/api-reference/resources/runners/methods/retrieve

Example cURL request to retrieve runner details.

```bash
curl https://app.gitpod.io/api/gitpod.v1.RunnerService/GetRunner \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

--------------------------------

### POST /gitpod.v1.EnvironmentAutomationService/StartService

Source: https://ona.com/docs/api-reference/resources/environments/methods/stop

Starts an automation service.

```APIDOC
## POST /gitpod.v1.EnvironmentAutomationService/StartService

### Description
Starts an automation service. This call does not block until the service is started.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentAutomationService/StartService

### Request Body
- **id** (string) - Required - The ID of the service to start.

### Request Example
{
  "id": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
}
```

--------------------------------

### POST /gitpod.v1.EnvironmentAutomationService/StartService

Source: https://ona.com/docs/api-reference/resources/environments/subresources/automations/methods/upsert

Starts an automation service.

```APIDOC
## POST /gitpod.v1.EnvironmentAutomationService/StartService

### Description
Starts an automation service. This call does not block until the service is started and will not error if the service is already running.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentAutomationService/StartService
```

--------------------------------

### Get Authenticated Identity Response

Source: https://ona.com/docs/api-reference/resources/identity/methods/get-authenticated-identity

Example response when retrieving details about the authenticated user.

```json
{
  "organizationId": "organizationId",
  "organizationTier": "organizationTier",
  "subject": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "principal": "PRINCIPAL_UNSPECIFIED"
  }
}
```

--------------------------------

### Get Editor Response

Source: https://ona.com/docs/api-reference/resources/editors/methods/retrieve

Example JSON response containing editor metadata and configuration.

```json
{
  "editor": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "installationInstructions": "installationInstructions",
    "name": "name",
    "urlTemplate": "urlTemplate",
    "alias": "alias",
    "iconUrl": "iconUrl",
    "shortDescription": "shortDescription",
    "versions": [
      {
        "version": "version"
      }
    ]
  }
}
```

--------------------------------

### Create multiple Automations from samples

Source: https://ona.com/docs/ona/automations/automations-as-code

Instantiate specific automation configurations from a repository.

```bash
ona ai automation create .ona/fix-dependabot-alert.yaml
ona ai automation create .ona/fix-codescan-alert.yaml
```

--------------------------------

### Create project

Source: https://ona.com/docs/api-reference/resources/projects/methods/bulk_create

Examples for creating projects with minimal configuration or with specific devcontainer settings.

```yaml
name: "Web Application"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/repo"
```

```yaml
name: "Backend Service"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/backend"
devcontainerFilePath: ".devcontainer/devcontainer.json"
automationsFilePath: ".gitpod/automations.yaml"
```

--------------------------------

### Get Organization Invite Summary cURL Example

Source: https://ona.com/docs/api-reference/resources/organizations/subresources/invites/methods/get_summary

Example cURL command to retrieve organization details and membership info based on an invite link. Ensure to replace $GITPOD_API_KEY with your actual API key.

```bash
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/GetOrganizationInviteSummary \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{ \
          "inviteId": "d2c94c27-3b76-4a42-b88c-95a85e392c68" \
        }'
```

--------------------------------

### Install from direct download

Source: https://ona.com/docs/ona/integrations/cli

Commands to make a manually downloaded binary executable and move it to the system path.

```bash
chmod +x ona
sudo mv ona /usr/local/bin
```

--------------------------------

### Get User API Request and Response

Source: https://ona.com/docs/api-reference/resources/users/methods/get_user

Example cURL request and JSON response for the GetUser method.

```bash
curl https://app.gitpod.io/api/gitpod.v1.UserService/GetUser \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

```json
{
  "user": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "avatarUrl": "avatarUrl",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "email": "email",
    "name": "name",
    "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "status": "USER_STATUS_UNSPECIFIED"
  }
}
```

--------------------------------

### POST /gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

Source: https://ona.com/docs/api-reference/resources/environments/methods/create_environment_token

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

```APIDOC
## POST /gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Description
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.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Parameters
#### Request Body
- **projectId** (string) - Required - The ID of the project to create the environment from.
- **spec** (object) - Optional - Custom specifications for the environment, such as machine class and timeout.
  - **machine** (object) - Optional - Specifies the machine class for the environment.
    - **class** (string) - Optional - The ID of the machine class.
  - **timeout** (object) - Optional - Specifies the timeout settings for the environment.
    - **disconnected** (string) - Optional - The duration in seconds after which the environment will be shut down if disconnected.

### Request Example
```json
{
  "projectId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047",
  "spec": {
    "machine": {
      "class": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
    },
    "timeout": {
      "disconnected": "14400s"
    }
  }
}
```

### Response
#### Success Response (200)
- **environment** (object) - Details of the created environment.
```

--------------------------------

### Create Environment From Project Examples

Source: https://ona.com/docs/api-reference/resources/environments/methods/mark_active

Creates environments based on project configurations, with options to override defaults.

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

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

--------------------------------

### Get SCM Integration via cURL

Source: https://ona.com/docs/api-reference/resources/runners/subresources/configurations/subresources/scm_integrations/methods/retrieve

Example request and response for retrieving SCM integration details.

```bash
curl https://app.gitpod.io/api/gitpod.v1.RunnerConfigurationService/GetSCMIntegration \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

```json
{
  "integration": {
    "id": "id",
    "host": "host",
    "oauth": {
      "clientId": "clientId",
      "encryptedClientSecret": "U3RhaW5sZXNzIHJvY2tz",
      "issuerUrl": "issuerUrl"
    },
    "pat": true,
    "runnerId": "runnerId",
    "scmId": "scmId",
    "virtualDirectory": "virtualDirectory"
  }
}
```

--------------------------------

### Verify environment setup

Source: https://ona.com/docs/ona/configuration/devcontainer/getting-started

Execute standard project commands to ensure the runtime and dependencies are correctly configured within the container.

```bash
# Check your runtime
node --version

# Run your tests (if your project has a test script)
npm test

# Start your dev server (if your project has a dev script)
npm run dev
```

--------------------------------

### Get ID Token Requests

Source: https://ona.com/docs/api-reference/resources/identity/methods/exchange-token

Examples for requesting ID tokens for single or multiple service audiences.

```yaml
audience:
  - "https://api.gitpod.io"
```

```yaml
audience:
  - "https://api.gitpod.io"
  - "https://ws.gitpod.io"
```

--------------------------------

### AGENTS.md Example: System Architecture

Source: https://ona.com/docs/ona/best-practices

This section of AGENTS.md guides agents to the .llm/ directory for architectural documentation.

```markdown
## System Architecture
For architectural understanding, refer to the .llm/ directory which contains
a high-level overview, entity glossary, and tech stack documentation.
```

--------------------------------

### POST /gitpod.v1.EnvironmentService/CreateEnvironment

Source: https://ona.com/docs/api-reference/resources/environments/methods/delete

Creates a development environment from a context URL and starts it.

```APIDOC
## POST /gitpod.v1.EnvironmentService/CreateEnvironment

### Description
Creates a development environment from a context URL (e.g. Git repository) and starts it. The `class` field must be a valid environment class ID.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/CreateEnvironment

### Request Body
- **spec** (object) - Required - Configuration for the environment including machine class and content initialization.

### Request Example
{
  "spec": {
    "machine": {
      "class": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
    },
    "content": {
      "initializer": {
        "specs": [
          { "contextUrl": { "url": "https://github.com/gitpod-io/gitpod" } }
        ]
      }
    }
  }
}

### Response
#### Success Response (200)
- **environment** (object) - The created environment object.
```

--------------------------------

### Create Basic Project

Source: https://ona.com/docs/api-reference/resources/projects/methods/retrieve

Creates a project with minimal configuration. Use this method to set up development projects, configure environments, define settings, or initialize content.

```yaml
name: "Web Application"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/repo"
```

--------------------------------

### POST /gitpod.v1.EnvironmentService/GetEnvironment

Source: https://ona.com/docs/api-reference/resources/environments/methods/mark_active

Gets details about a specific environment including its status, configuration, and context URL. Use this method to check environment readiness, get connection details, monitor health, and debug setup issues.

```APIDOC
## POST /gitpod.v1.EnvironmentService/GetEnvironment

### Description
Gets details about a specific environment including its status, configuration, and context URL. Use this method to check if an environment is ready to use, get connection details for IDE and exposed ports, monitor environment health and resource usage, and debug environment setup issues.

### Request Body
```json
{
  "environmentId": "07e03a28-65a5-4d98-b532-8ea67b188048"
}
```
```

--------------------------------

### Create Environment From Project

Source: https://ona.com/docs/api-reference/resources/environments/methods/create

Creates a new Gitpod environment based on an existing project configuration and initiates its startup. Project settings are used as defaults, but can be overridden by custom specifications in the request.

```APIDOC
## POST /gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Description
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.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Parameters
#### Request Body
- **projectId** (string) - Required - The ID of the project to create the environment from.
- **environmentVariables** (object) - Optional - A map of environment variables to set for the new environment.
- **containerRegistryBasicAuthHost** (string) - Optional - Host for container registry basic authentication.
- **credentialProxy** (object) - Optional - Configuration for a credential proxy.
  - **format** (string) - Optional - Format of the credential proxy.
  - **header** (string) - Optional - Header for the credential proxy.
  - **targetHosts** (array of strings) - Optional - Target hosts for the credential proxy.
- **environmentVariable** (string) - Optional - An environment variable.
- **filePath** (string) - Optional - Path to a file.
- **gitCredentialHost** (string) - Optional - Host for Git credential authentication.
- **name** (string) - Optional - Name of the environment.
- **scope** (string) - Optional - Scope of the environment.
- **session** (string) - Optional - Session information.
- **source** (string) - Optional - Source of the environment configuration.
- **sourceRef** (string) - Optional - Reference to the source.
- **specVersion** (string) - Optional - Version of the specification.
- **sshPublicKeys** (array of objects) - Optional - List of SSH public keys to associate with the environment.
  - **id** (string) - Required - ID of the SSH public key.
  - **value** (string) - Required - Value of the SSH public key.
- **timeout** (object) - Optional - Timeout configuration for the environment.
  - **disconnected** (string) - Optional - Disconnected timeout duration (e.g., "+9125115.360s").
- **workflowActionId** (string) - Optional - ID of the workflow action.

### Response
#### Success Response (200)
- **environment** (object) - Details of the created environment.
  - **id** (string) - The unique identifier of the environment.
  - **status** (object) - The current status of the environment.
    - **activitySignal** (object) - Signal indicating activity.
      - **source** (string) - Source of the activity signal.
      - **timestamp** (string) - Timestamp of the activity signal.
    - **automationsFile** (object) - Status of the automations file.
      - **automationsFilePath** (string) - Path to the automations file.
      - **automationsFilePresence** (string) - Presence status of the automations file.
      - **failureMessage** (string) - Failure message, if any.
      - **phase** (string) - Current phase of the automations file processing.
      - **session** (string) - Session ID for automations file processing.
      - **warningMessage** (string) - Warning message, if any.
    - **content** (object) - Status of the environment content.
      - **contentLocationInMachine** (string) - Location of the content within the machine.
      - **failureMessage** (string) - Failure message, if any.
      - **git** (object) - Git-related status information.
        - **branch** (string) - Current Git branch.
        - **changedFiles** (array of objects) - List of changed files.
          - **changeType** (string) - Type of change.
          - **path** (string) - Path of the changed file.
        - **cloneUrl** (string) - Clone URL of the repository.
        - **latestCommit** (string) - Latest commit hash.
        - **totalChangedFiles** (integer) - Total number of changed files.
        - **totalUnpushedCommits** (integer) - Total number of unpushed commits.
        - **unpushedCommits** (array of strings) - List of unpushed commit hashes.
      - **phase** (string) - Current phase of content processing.
      - **session** (string) - Session ID for content processing.
      - **warningMessage** (string) - Warning message, if any.
    - **devcontainer** (object) - Status of the devcontainer.
      - **containerId** (string) - ID of the devcontainer.
      - **containerName** (string) - Name of the devcontainer.
      - **devcontainerconfigInSync** (boolean) - Indicates if devcontainer config is in sync.
      - **devcontainerFilePath** (string) - Path to the devcontainer configuration file.
      - **devcontainerFilePresence** (string) - Presence status of the devcontainer file.
      - **failureMessage** (string) - Failure message, if any.
      - **phase** (string) - Current phase of devcontainer setup.
      - **remoteUser** (string) - Remote user in the devcontainer.
      - **remoteWorkspaceFolder** (string) - Remote workspace folder path.
      - **secretsInSync** (boolean) - Indicates if secrets are in sync.
      - **session** (string) - Session ID for devcontainer setup.
      - **warningMessage** (string) - Warning message, if any.
    - **environmentUrls** (object) - URLs related to the environment.
      - **logs** (string) - URL for environment logs.
      - **ops** (string) - URL for operations.
      - **ports** (array of objects) - List of exposed ports and their URLs.
        - **port** (integer) - The port number.
        - **url** (string) - The URL for the exposed port.
      - **ssh** (object) - SSH connection details.
        - **url** (string) - SSH connection URL.
      - **supportBundle** (string) - URL for support bundle.
      - **vmLiveUsage** (string) - URL for VM live usage statistics.
    - **failureMessage** (array of strings) - List of failure messages.
    - **machine** (object) - Status of the underlying machine.
      - **dualDisk** (boolean) - Indicates if the machine has dual disks.
      - **failureMessage** (string) - Failure message, if any.
      - **phase** (string) - Current phase of the machine lifecycle.
      - **session** (string) - Session ID for machine status.
      - **timeout** (string) - Timeout configuration for the machine.
      - **versions** (object) - Version information for the machine components.
        - **amiId** (string) - AMI ID of the machine image.
        - **supervisorCommit** (string) - Git commit hash of the supervisor.
        - **supervisorVersion** (string) - Version of the supervisor.
      - **warningMessage** (string) - Warning message, if any.
    - **phase** (string) - Overall environment phase.
    - **runnerAck** (object) - Acknowledgment from the runner.
      - **message** (string) - Acknowledgment message.
      - **specVersion** (string) - Specification version.
      - **statusCode** (string) - Status code of the acknowledgment.
    - **secrets** (array of objects) - Status of secrets management.
      - **id** (string) - ID of the secret.
      - **failureMessage** (string) - Failure message, if any.
      - **phase** (string) - Current phase of secret processing.
      - **secretName** (string) - Name of the secret.
      - **session** (string) - Session ID for secret processing.
      - **warningMessage** (string) - Warning message, if any.
    - **sshPublicKeys** (array of objects) - Status of SSH public key configuration.
      - **id** (string) - ID of the SSH public key.
      - **phase** (string) - Current phase of SSH public key processing.
    - **statusVersion** (string) - Version of the status information.
    - **warningMessage** (array of strings) - List of warning messages.

#### Response Example
```json
{
  "environment": {
    "id": "your_environment_id",
    "status": {
      "phase": "ENVIRONMENT_PHASE_RUNNING",
      "content": {
        "phase": "CONTENT_PHASE_COMPLETE"
      },
      "devcontainer": {
        "phase": "PHASE_COMPLETE"
      },
      "machine": {
        "phase": "PHASE_COMPLETE"
      }
    }
  }
}
```
```

--------------------------------

### Get Organization Policies via cURL

Source: https://ona.com/docs/api-reference/resources/organizations/subresources/policies/methods/retrieve

Example request to retrieve organization policies using the Gitpod API.

```bash
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/GetOrganizationPolicies \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'
```

--------------------------------

### Create Environment From Project

Source: https://ona.com/docs/api-reference/resources/environments/methods/create_logs_token

Creates a new Gitpod environment based on an existing project configuration and initiates its startup. Project settings are used as defaults, but can be overridden by custom specifications in the request.

```APIDOC
## POST /gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Description
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.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Parameters
#### Request Body
- **projectId** (string) - Required - The ID of the project to create the environment from.
- **environmentVariables** (object) - Optional - A map of environment variables to set for the new environment.
- **containerRegistryBasicAuthHost** (string) - Optional - Host for container registry basic authentication.
- **credentialProxy** (object) - Optional - Configuration for a credential proxy.
  - **format** (string) - Optional - Format of the credential proxy.
  - **header** (string) - Optional - Header for the credential proxy.
  - **targetHosts** (array) - Optional - Target hosts for the credential proxy.
- **environmentVariable** (string) - Optional - An environment variable.
- **filePath** (string) - Optional - Path to a file.
- **gitCredentialHost** (string) - Optional - Host for Git credential authentication.
- **name** (string) - Optional - Name of the environment.
- **scope** (string) - Optional - Scope of the environment.
- **session** (string) - Optional - Session information.
- **source** (string) - Optional - Source of the environment configuration.
- **sourceRef** (string) - Optional - Reference to the source.
- **specVersion** (string) - Optional - Version of the specification.
- **sshPublicKeys** (array) - Optional - List of SSH public keys to associate with the environment.
  - **id** (string) - Required - ID of the SSH public key.
  - **value** (string) - Required - Value of the SSH public key.
- **timeout** (object) - Optional - Timeout configuration for the environment.
  - **disconnected** (string) - Optional - Disconnected timeout duration.

### Response
#### Success Response (200)
- **environment** (object) - Details of the created environment.
  - **id** (string) - The unique identifier for the environment.
  - **name** (string) - The name of the environment.
  - **status** (object) - The current status of the environment.
    - **phase** (string) - The current phase of the environment lifecycle.
    - **automationsFile** (object) - Status of the automations file processing.
    - **content** (object) - Status of the content processing.
    - **devcontainer** (object) - Status of the devcontainer setup.
    - **environmentUrls** (object) - URLs for accessing the environment's services.
    - **machine** (object) - Status of the underlying machine.
    - **runnerAck** (object) - Acknowledgment status from the runner.
    - **secrets** (array) - Status of secrets synchronization.
    - **sshPublicKeys** (array) - Status of SSH public key synchronization.
    - **failureMessage** (array) - List of failure messages.
    - **warningMessage** (array) - List of warning messages.

#### Response Example
```json
{
  "environment": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "my-dev-environment",
    "status": {
      "phase": "ENVIRONMENT_PHASE_RUNNING",
      "automationsFile": {
        "automationsFilePath": "/path/to/automations.yaml",
        "automationsFilePresence": "PRESENT",
        "phase": "CONTENT_PHASE_COMPLETE"
      },
      "content": {
        "contentLocationInMachine": "/workspace",
        "phase": "CONTENT_PHASE_COMPLETE",
        "git": {
          "branch": "main",
          "changedFiles": [],
          "cloneUrl": "https://github.com/user/repo.git",
          "latestCommit": "abcdef1234567890",
          "totalChangedFiles": 0,
          "totalUnpushedCommits": 0
        }
      },
      "devcontainer": {
        "containerId": "container-12345",
        "containerName": "gitpod-workspace",
        "devcontainerconfigInSync": true,
        "devcontainerFilePath": ".devcontainer/devcontainer.json",
        "devcontainerFilePresence": "PRESENT",
        "phase": "PHASE_COMPLETE",
        "remoteUser": "gitpod",
        "remoteWorkspaceFolder": "/workspace",
        "secretsInSync": true
      },
      "environmentUrls": {
        "logs": "/logs/environment-id",
        "ops": "/ops/environment-id",
        "ports": [
          {
            "port": 8080,
            "url": "http://localhost:8080"
          }
        ],
        "ssh": {
          "url": "ssh://user@host:port"
        },
        "supportBundle": "/support/bundle/environment-id",
        "vmLiveUsage": "/vm/usage/environment-id"
      },
      "machine": {
        "dualDisk": false,
        "phase": "PHASE_COMPLETE",
        "versions": {
          "amiId": "ami-0123456789abcdef0",
          "supervisorCommit": "abcdef123",
          "supervisorVersion": "1.0.0"
        }
      },
      "runnerAck": {
        "message": "Runner acknowledged.",
        "statusCode": "OK"
      },
      "secrets": [
        {
          "id": "secret-1",
          "secretName": "MY_SECRET",
          "phase": "CONTENT_PHASE_COMPLETE"
        }
      ],
      "sshPublicKeys": [
        {
          "id": "key-1",
          "phase": "CONTENT_PHASE_COMPLETE"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Get Authenticated Identity cURL Request

Source: https://ona.com/docs/api-reference/resources/identity/methods/get-authenticated-identity

Example cURL command to retrieve information about the currently authenticated identity.

```bash
curl https://app.gitpod.io/api/gitpod.v1.IdentityService/GetAuthenticatedIdentity \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

--------------------------------

### Get Editor cURL Request

Source: https://ona.com/docs/api-reference/resources/editors/methods/retrieve

Example cURL request to retrieve editor details using an API key.

```bash
curl https://app.gitpod.io/api/gitpod.v1.EditorService/GetEditor \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "id": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
        }'
```

--------------------------------

### POST /gitpod.v1.PrebuildService/CreatePrebuild

Source: https://ona.com/docs/api-reference/resources/prebuilds/methods/delete

Creates a new prebuild for a project to enable faster environment startup.

```APIDOC
## POST /gitpod.v1.PrebuildService/CreatePrebuild

### Description
Creates a prebuild for a project. The process creates an environment, runs the devcontainer prebuild lifecycle, and creates a snapshot.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/CreatePrebuild

### Request Body
- **projectId** (string) - Required - The ID of the project.
- **environmentClassId** (string) - Optional - The specific environment class ID.
- **spec** (object) - Optional - Configuration including timeout settings.
```

--------------------------------

### Get SSO Configuration Request and Response

Source: https://ona.com/docs/api-reference/resources/organizations/subresources/sso_configurations/methods/retrieve

Example cURL request and JSON response for retrieving SSO configuration details.

```bash
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/GetSSOConfiguration \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "ssoConfigurationId": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
        }'
```

```json
{
  "ssoConfiguration": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "issuerUrl": "issuerUrl",
    "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "providerType": "PROVIDER_TYPE_UNSPECIFIED",
    "state": "SSO_CONFIGURATION_STATE_UNSPECIFIED",
    "additionalScopes": [
      "string"
    ],
    "claims": {
      "foo": "string"
    },
    "claimsExpression": "claimsExpression",
    "clientId": "clientId",
    "displayName": "displayName",
    "emailDomain": "emailDomain",
    "emailDomains": [
      "sfN2.l.iJR-BU.u9JV9.a.m.o2D-4b-Jd.0Z-kX.L.n.S.f.UKbxB"
    ]
  }
}
```

--------------------------------

### Initialize automations configuration

Source: https://ona.com/docs/ona/reference/cli

Run 'ona automations init' to set up the initial configuration files for automations.

```bash
ona automations init
```

--------------------------------

### Run Command in Ona Environment (Python)

Source: https://ona.com/docs/ona/integrations/sdk

This Python example demonstrates creating an environment from a Git repository, waiting for it to be ready, executing a command, printing the output, and then deleting the environment. It utilizes the AsyncGitpod client and utility functions for environment and command management.

```python
import asyncio
from gitpod import AsyncGitpod
import gitpod.lib as util

repo_url = "https://github.com/containerd/containerd"
command_to_execute = "go test -v -short ./..."

async def execute_command_in_environment():
    client = AsyncGitpod()

    machine_class_id = (await util.find_most_used_environment_class(client)).id

    create_params = {
        "machine": {"class": machine_class_id},
        "content": {"initializer": {"specs": [{"context_url": {"url": repo_url}}]}}
    }

    environment = (await client.environments.create(spec=create_params)).environment

    await util.wait_for_environment_running(client, environment.id)

    async for line in await util.run_command(client, environment.id, command_to_execute):
        print(line)

    await client.environments.delete(environment_id=environment.id)

if __name__ == "__main__":
    asyncio.run(execute_command_in_environment())
```