Ona

https://ona.com/docs/ona/
Admin
Ona runs AI coding agents in cloud development environments with tools for automation and team...
Tokens:153,453
Snippets:2,382
Trust Score:9.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Full Workflow Example

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

An end-to-end bash script demonstrating the creation, starting, command execution, and deletion of an environment. It includes waiting for the environment to be running and executing commands like 'npm install' and 'npm test'.

```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"
```

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

### Install Gitpod SDK for Go

Source: https://ona.com/docs/ona/api-reference

Install the Gitpod SDK for Go using the go get command. Ensure you specify the version for compatibility.

```go
go get -u 'github.com/gitpod-io/gitpod-sdk-go@v0.13.0'
```

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

### Install Dependencies During Prebuild and Post-Start

Source: https://ona.com/docs/ona/projects/prebuilds-setup

This example shows how to configure a task to install dependencies during both prebuilds and when a user rebuilds their Dev Container, ensuring node_modules are available in the snapshot and after rebuilds.

```yaml
tasks:
  install-deps:
    name: Install dependencies
    triggeredBy:
      - prebuild
      - postDevcontainerStart
    command: npm ci
```

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

### Install fzf with Dependency Check

Source: https://ona.com/docs/ona/configuration/dotfiles/overview

Example of a self-contained install script snippet that checks for the 'fzf' command and installs it if missing. It downloads, extracts, and moves the binary, then sources its completion script.

```bash
FZF_VERSION="0.60.3"
if ! command -v fzf >/dev/null 2>&1; then
    curl -L "https://github.com/junegunn/fzf/releases/download/v${FZF_VERSION}/fzf-${FZF_VERSION}-linux_amd64.tar.gz" | tar xzf -
    sudo mv fzf /usr/local/bin
fi
echo "source <(fzf --zsh)" >> "$HOME/.zshrc"
```

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

### Configure Preview Server

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

Sets up a preview server to serve your application for testing. It installs dependencies, builds the application, and starts a server on port 3000.

```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
```

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

### Configure Startup Tasks and Services

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

Automate dependency installation and start services like a PostgreSQL database on environment startup. This ensures all necessary components are ready before development begins.

```yaml
# .ona/automations.yaml
tasks:
  install:
    name: Install dependencies
    command: npm install
    triggeredBy:
      - postDevcontainerStart

services:
  database:
    name: PostgreSQL
    commands:
      start: docker run --rm -t --name database -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:15
      ready: docker exec database pg_isready
      stop: docker stop database
    triggeredBy:
      - postEnvironmentStart
```

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

### Example automations.yaml Configuration

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

Defines a PostgreSQL service that starts on environment setup and a task to seed the database, which depends on the database service. Also includes a task to run tests triggered manually.

```yaml
services:
  database:
    name: PostgreSQL
    commands:
      start: docker compose up postgres
      ready: docker compose exec postgres pg_isready
    triggeredBy:
      - postDevcontainerStart

tasks:
  seed:
    name: Seed database
    command: npm run db:seed
    dependsOn:
      - database
    triggeredBy:
      - postDevcontainerStart

  test:
    name: Run tests
    command: npm test
    triggeredBy:
      - manual
```

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

### Setup Troubleshooting Task

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

This YAML snippet defines a manual task to set up troubleshooting for production issues. It installs htop and iftop, and runs a VPN setup script.

```yaml
tasks:
  troubleshoot:
    name: Setup troubleshooting
    triggeredBy:
      - manual
    command: |
      sudo apt-get update && sudo apt-get install -y htop iftop
      ./scripts/setup-vpn.sh
```

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

### Examples of Opening Repositories from Different Providers

Source: https://ona.com/docs/ona/integrations/ona-url

Examples demonstrating how to open repositories from GitHub, GitLab, and Bitbucket using the Ona URL format.

```url
https://app.ona.com/#https://github.com/gitpod-io/empty
```

```url
https://app.ona.com/#https://gitlab.com/gitpod-io/empty
```

```url
https://app.ona.com/#https://bitbucket.org/gitpod-io/empty
```

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

### Verify Node.js Environment Setup

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

Check your Node.js runtime version, run project tests, and start your development server to confirm the Dev Container is configured correctly.

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

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

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

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

### Start Preview Server for Prototype

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

Use this prompt to start a preview server for a generated prototype and obtain its URL. This is part of the verification step for the prototype generation workflow.

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

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

### Service Definition Example

Source: https://ona.com/docs/ona/reference/automations-yaml-schema

Defines two services: 'database' for PostgreSQL and 'backend' for an application. The database service includes start, ready, and stop commands using Docker. The backend service specifies its role and start command.

```yaml
services:
  database:
    name: PostgreSQL
    description: The backend database
    triggeredBy:
      - postEnvironmentStart
    commands:
      start: docker run --rm --name database postgres:latest
      ready: docker exec database pg_isready
      stop: docker stop database

  backend:
    name: Application Backend
    description: The application backend
    role: default
    triggeredBy:
      - postEnvironmentStart
    commands:
      start: cd backend && go run main.go
```

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

### Service Trigger Example

Source: https://ona.com/docs/ona/reference/automations-yaml-schema

Start a service during prebuilds using 'prebuild' and 'postDevcontainerStart' triggers so that prebuild tasks can depend on it. Always define a 'ready' command for prebuild services to ensure initialization is complete before snapshotting.

```yaml
services:
  database:
    name: Database server
    commands:
      start: docker run --rm --name database -p 5432:5432 postgres:16
      ready: docker exec database pg_isready
    triggeredBy:
      - prebuild
      - postDevcontainerStart
```

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

### Example AGENTS.md for Project Guidelines

Source: https://ona.com/docs/ona/agents-md

A comprehensive example of an AGENTS.md file covering commands, project structure, conventions, and security. It includes important commands and security warnings.

```markdown
# Project Guidelines

## Commands
- `npm test` - Run test suite (required before PR)
- `npm run build` - Production build
- `npm run dev` - Start dev server at localhost:3000
- `npm run typecheck` - TypeScript validation

**IMPORTANT**: Run `npm test` and `npm run typecheck` before creating a PR.

## Project Structure
- `src/components/` - Reusable UI components
- `src/features/` - Feature-specific code
- `src/lib/` - Shared utilities

## Conventions
- TypeScript for all files
- Components: PascalCase (`UserCard.tsx`)
- Branch naming: `initials/short-description`

## Security
**NEVER** commit `.env` files or hardcode API keys.
Run `npm run security-check` before merging to main.
```

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

### Install Ona SDKs

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

Install the Ona SDK for Python, Node/TypeScript, or Go using their respective package managers.

```bash
# Python
pip install gitpod-sdk

# Node/TypeScript
npm install @gitpod/sdk

# Go
go get github.com/gitpod-io/gitpod-sdk-go
```

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

### Example Atlassian Agent Prompts

Source: https://ona.com/docs/ona/integrations/configure-atlassian

These are example prompts you can use with an agent after connecting Atlassian. They demonstrate common tasks like creating issues, searching documentation, and updating ticket statuses.

```text
"Create a Jira issue for this authentication bug with the stack trace"

"Search Confluence for the API rate limiting design doc"

"Move issue PROJ-456 to In Progress and add a comment that I'm starting work"

"Find any existing Jira issues about database timeouts before I create a new one"
```

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

### Complete Automations YAML Example

Source: https://ona.com/docs/ona/reference/automations-yaml-schema

This comprehensive example demonstrates various configurations for services and tasks, including running containers, executing commands, setting dependencies, and defining triggers.

```yaml
services:
  # Containerized service using docker run
  redis:
    name: Redis Cache
    description: In-memory cache for session data
    role: default
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: |
        if docker inspect redis >/dev/null 2>&1; then
          docker start -a redis
        else
          docker run --name redis -p 6379:6379 redis:7-alpine redis-server --appendonly yes
        fi
      ready: docker exec redis redis-cli ping | grep -q PONG
      stop: docker stop redis

  # Service running in the Dev Container
  backend:
    name: API Server
    description: Main application backend
    triggeredBy:
      - postDevcontainerStart
      - manual
    commands:
      start: cd backend && go run main.go
      ready: curl -sf http://localhost:8080/health

  # AI agent service
  code-assistant:
    name: Code Assistant
    description: AI-powered code analysis
    role: ai-agent
    triggeredBy:
      - manual
    commands:
      start: ./bin/assistant serve

tasks:
  # Task that runs during prebuild (no user secrets available)
  install-deps:
    name: Install dependencies
    description: Install all project dependencies
    triggeredBy:
      - prebuild
      - postDevcontainerStart
    command: npm ci && go mod download

  # Task with dependencies on other tasks
  build:
    name: Build project
    description: Compile all source code
    dependsOn:
      - install-deps
    command: npm run build && go build ./...

  # Lint task
  lint:
    name: Lint code
    description: Run linters
    command: golangci-lint run ./...

  # Manual task for running tests
  test:
    name: Run tests
    description: Execute the full test suite
    triggeredBy:
      - manual
    dependsOn:
      - build
    command: npm test && go test -v ./...
```

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

### Run Redis in a Docker Container

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

This example shows how to start a Redis service in a Docker container. It includes logic to reuse an existing container if it already exists, and it's triggered after the devcontainer starts.

```yaml
services:
  redis:
    name: Redis
    description: In-memory cache
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: |
        if docker inspect redis >/dev/null 2>&1;
        then
          docker start -a redis
        else
          docker run --name redis -p 6379:6379 \
            -e REDIS_MAXMEMORY=256mb \
            -e REDIS_MAXMEMORY_POLICY=allkeys-lru \
            redis:7-alpine
        fi
      ready: docker exec redis redis-cli ping | grep -q PONG
      stop: docker stop redis
```

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

### Example Notion Agent Workflows

Source: https://ona.com/docs/ona/integrations/configure-notion

These are example natural language prompts you can use with agents to interact with your Notion workspace. They demonstrate searching for specific documents, finding runbooks, and creating new pages.

```text
Search Notion for the API design doc for the payments service
```

```text
Find the onboarding runbook in Notion
```

```text
What does the Notion page about our database migration plan say?
```

```text
Create a Notion page summarizing the changes I made to the auth module
```

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

### Example Automation Steps

Source: https://ona.com/docs/ona/create-first-automation

Illustrates the sequence of steps for a dependency update automation, including a prompt, command execution, and pull request creation.

```text
Update all dependencies to their latest compatible versions.
Run the test suite and fix any breaking changes.
```

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

### Start, Stop, Delete, SSH, and Logs

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

Commands to manage the lifecycle and access of an environment.

```bash
ona environment start <id-or-name>
```

```bash
ona environment stop <id-or-name>
```

```bash
ona environment delete <id-or-name>
```

```bash
ona environment ssh <id-or-name>
```

```bash
ona environment logs <id-or-name>
```

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

### Start Task or Service with CLI

Source: https://ona.com/docs/ona/reference/automations-yaml-schema

Commands to start a specific task or service within the Ona environment.

```bash
ona automations service start ...
```

```bash
ona automations task start ...
```

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

### Install Gitpod SDK

Source: https://ona.com/docs/ona/audit-logs/overview

Install the official Gitpod SDK using pip. Ensure your GITPOD_API_KEY environment variable is set.

```bash
pip install gitpod-sdk
```

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

### Example Automation Workflow

Source: https://ona.com/docs/ona/automations/configure-automations

This example demonstrates a sequence of steps in an automation workflow, including a prompt for dependency upgrades, a command for testing, and a pull request for submitting changes.

```text
Step 1 (Prompt):    "Upgrade all dependencies to their latest versions"
Step 2 (Command):   npm test
Step 3 (PR):        Create pull request with summary
```

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

### Start and Stop Environments

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

Commands to start or stop a specific environment using its ID or name.

```bash
ona environment start <id-or-name>
```

```bash
ona environment stop <id-or-name>
```

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

### Install CLI using Homebrew

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

Install the CLI on macOS and Linux using the Homebrew package manager. The formula handles OS and architecture detection automatically.

```bash
brew install gitpod-io/tap/ona
```

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

### Skill Directory Structure Example

Source: https://ona.com/docs/ona/agents/skills

Illustrates a typical directory structure for custom skills within the .ona/skills/ directory.

```bash
.ona/skills/
├── create-pr/
│   └── SKILL.md
├── deploy-staging/
│   └── SKILL.md
└── debug-performance/
    └── SKILL.md

```

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

### CLI Commands for Prebuild Management

Source: https://ona.com/docs/ona/projects/prebuilds-management

A collection of common CLI commands for listing, getting details of, and deleting prebuilds.

```bash
# List prebuilds
ona prebuild list --project-id <project-id>

# Get prebuild details
ona prebuild get <prebuild-id>

# Delete a prebuild
ona prebuild delete <prebuild-id>
```

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

### Verify Linear Connection

Source: https://ona.com/docs/ona/integrations/configure-linear

Use this prompt to confirm that your Linear integration is working correctly after setup.

```text
Show me my open Linear issues
```

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

### Start a Code Review

Source: https://ona.com/docs/ona/integrations/github-pr-mentions

Use this snippet to initiate a code review. The agent will run with a default prompt.

```text
@ona-agent
```

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

### Verify CLI installation using SLSA verification script

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

Install the CLI with SLSA verification enabled to ensure the integrity and authenticity of the downloaded artifact. This requires jq, openssl, and curl.

```bash
curl -fsSL https://app.gitpod.io/releases/cli/install.sh | VERIFY_SLSA=true bash
```

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

### Python SDK: Create Environment and Run Command

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

This example demonstrates creating a new environment from a Git repository, waiting for it to be ready, executing a command, printing its output, and then cleaning up the environment. It utilizes utility functions for finding environment classes, waiting, and running commands.

```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 = {
        "desired_phase": "ENVIRONMENT_PHASE_RUNNING",
        "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())
```

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

### Create Services for Monorepo Components

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

This example finds directories within `./components`, formats them into service configurations using `jq`, and pipes them to `ona automations update`. It assumes Go projects with a `main.go` file.

```bash
find ./components -type d -maxdepth 1 -mindepth 1 | jq -R '{(. | gsub("[^a-zA-Z0-9_-"]"; "_")): {"name": "Start " + ., "command": "cd " + . + " && go run ."}}' | jq -s 'add | {"services": .}' | ona automations update -
```

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

### Create Automations from Real-world Example Files

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

Instantiate Automations using YAML files from a real-world sample project. This demonstrates how to apply Automations for tasks like fixing security alerts.

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

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

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

### Minimal automations.yaml

Source: https://ona.com/docs/ona/create-first-automation

Defines a task to install dependencies when the devcontainer starts. Place this file at .devcontainer/automations.yaml.

```yaml
tasks:
  install:
    name: Install dependencies
    command: npm ci
    triggeredBy:
      - postDevcontainerStart
```

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

### Non-blocking Environment Creation

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

Use `--dont-wait` to immediately receive the environment ID without waiting for it to start. You can then poll for readiness using `ona environment get`.

```bash
ENV_ID=$(ona environment create <project-id> --dont-wait)
```

```bash
ona environment get "$ENV_ID" -o json
```

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

### Create a Project

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

Initiates the creation of a new project, requiring the repository URL.

```bash
ona project create <repo-url>
```

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

### Configure Jupyter Notebook Service

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

Starts a Jupyter Notebook server for data science tasks. It installs necessary Python packages and makes the notebook accessible on port 8888.

```yaml
services:
  jupyter:
    name: Jupyter Notebook
    triggeredBy:
      - manual
    commands:
      start: |
        pip install jupyter pandas numpy matplotlib
        jupyter notebook --ip=0.0.0.0 --no-browser
      ready: curl -sf http://localhost:8888 > /dev/null
```

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

### Assume AWS Role and Get Secret Value

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

Use this command to assume an AWS role and then retrieve a secret value from AWS Secrets Manager. Ensure the AWS CLI is installed and configured.

```bash
ona idp login aws --role-arn <your-iam-role-arn> [--duration-seconds=<expiry-in-seconds>]
aws secretsmanager get-secret-value --secret-id database_connection_string --region us-east-1 | jq .SecretString
```

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

### Make downloaded binary executable and move to PATH

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

After downloading the CLI binary directly, make it executable and place it in your system's PATH for easy access. This is a common step for manual installations.

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

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

### Start PostgreSQL and Seed Database

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

This snippet demonstrates how to start a PostgreSQL database in a Docker container and seed it with development data using a shell script. It's triggered after the devcontainer starts.

```yaml
services:
  postgresql:
    name: PostgreSQL
    description: Development database
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: docker run --rm --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15
      ready: docker exec postgres pg_isready -U postgres
      stop: docker stop postgres

tasks:
  seed:
    name: Seed database
    triggeredBy:
      - manual
    command: ./scripts/seed-dev-db.sh
```

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

### Start Automation Task

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

Starts a specific automation task, such as a build process, within a designated environment.

```bash
ona automations task start build --environment-id api-dev
```

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

### Open Port and Preview in Browser

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

Opens a specified port and launches the preview URL in the default browser. Ensure the port number is valid and the application is running.

```bash
$BROWSER "$(ona environment port open 8000 -n my-app)"
```

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

### Example Agent Prompts for Linear

Source: https://ona.com/docs/ona/integrations/configure-linear

These are example natural language prompts you can use to interact with agents for Linear tasks.

```text
"Create a Linear issue for this authentication bug with the stack trace"

"Show me all high-priority issues assigned to me in the API project"

"Move issue ABC-123 to In Progress and add a comment that I'm starting work"

"Find any existing issues about rate limiting before I create a new one"
```

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

### Basic URL Format for Opening Repositories

Source: https://ona.com/docs/ona/integrations/ona-url

Prefix any repository URL with https://app.ona.com/# to create an environment directly from that repository.

```url
https://app.ona.com/#<repository-url>
```

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

### Example Sentry Agent Workflows

Source: https://ona.com/docs/ona/integrations/configure-sentry

These are example natural language prompts agents can use to interact with Sentry for issue analysis and monitoring.

```natural_language
Show me the most frequent unresolved Sentry issues in production
```

```natural_language
What's the stack trace for issue SENTRY-1234?
```

```natural_language
Find any Sentry errors related to the payment processing module
```

```natural_language
Were there any new errors after the last deployment?
```

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

### Customized Subject Claim Example

Source: https://ona.com/docs/ona/configuration/oidc

An example of a customized subject claim (`sub`) that includes an additional field, `creator_email`, to create more specific trust policies.

```text
organization_id:<orgID>:environment_id:<envID>:creator_email:dev@example.com
```

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

### Prebuild Optimization with Multiple Commands

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

Install dependencies for npm, Go, and Python during prebuild. Ensure all necessary dependencies are cached before subsequent build steps.

```yaml
tasks:
  install-deps:
    name: Install dependencies
    description: Install and cache all dependencies
    triggeredBy:
      - prebuild
    command: |
      npm ci
      go mod download
      pip install -r requirements.txt

  build-assets:
    name: Build static assets
    description: Compile CSS and bundle JavaScript
    triggeredBy:
      - prebuild
    dependsOn:
      - install-deps
    command: npm run build:assets

  warm-cache:
    name: Warm build cache
    description: Pre-compile common modules
    triggeredBy:
      - prebuild
    dependsOn:
      - install-deps
    command: go build -v ./...
```

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

### Install Gitpod SDK for TypeScript

Source: https://ona.com/docs/ona/api-reference

Install the Gitpod SDK for TypeScript using npm. This is the first step to integrating Gitpod's functionality into your TypeScript projects.

```typescript
npm install @gitpod/sdk
```

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

### Verify Notion Connection

Source: https://ona.com/docs/ona/integrations/configure-notion

A sample prompt to verify that the Notion integration is working correctly after setup. Use this in an agent session to check if results from your workspace are returned.

```text
Search Notion for our project documentation
```

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

### Create Environment from Context URL

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

Create an environment using a repository URL and a specified environment class ID.

```bash
ona environment create <repo-url> --class-id <class-id>
```

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

### Example API Response Structure

Source: https://ona.com/docs/ona/audit-logs/overview

This is an example of the JSON response structure you can expect when querying audit logs via the REST API. It includes log entries and pagination information.

```json
{
  "entries": [
    {
      "id": "01951d94-d6ac-7edf-9021-a044cfd1908f",
      "actorId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
      "actorPrincipal": "PRINCIPAL_USER",
      "subjectId": "0194f5dd-01ca-75f4-a200-74381ed43f86",
      "subjectType": "RESOURCE_TYPE_ENVIRONMENT",
      "action": "changed status, phase",
      "createdAt": "2025-02-21T12:10:05Z"
    }
  ],
  "pagination": {
    "nextToken": "eyJpZCI6IjAxOTUxZDk0LWQ2YWMtN2VkZi05MDIxLWEwNDRjZmQxOTA4ZiJ9"
  }
}
```

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

### Manage Environment and Task Lifecycle

Source: https://ona.com/docs/ona/reference/automations-yaml-schema

This script demonstrates creating an environment, adding a task, running it, waiting for completion, and then stopping the environment. It's useful for testing or CI/CD pipelines.

```bash
# ona env create will set the environment context to the newly created env
ona env create https://github.com/some/repo

# add the task to the environment
cat <<EOF | ona automations update -
tasks:
  build:
    command: go build ./...
EOF

# run it
ona automations task start build

# stop the environment
ona env stop
```

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

### Deploy Terraform Infrastructure

Source: https://ona.com/docs/ona/custom-domain

Initializes Terraform, plans the deployment, and applies the configuration to create the custom domain infrastructure on GCP.

```bash
terraform init
terraform plan
terraform apply
```

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

### Install CLI using curl and mv

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

Download the CLI binary directly using curl, make it executable, and move it to your system's PATH. This method is suitable for macOS and Linux.

```bash
curl -o ona -fsSL "https://app.gitpod.io/releases/cli/stable/gitpod-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/arm64/arm64/i')" && \
chmod +x ona && \
sudo mv ona /usr/local/bin
```

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

### Automated Environment, Task, and Cleanup Workflow

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

This script demonstrates creating an environment, running a 'build-and-test' task, streaming its logs, checking the status, and cleaning up the environment if the task succeeds. Replace `<your-env-class-id>` with your actual environment class ID.

```bash
# Create environment
ENV_ID=$(ona environment create https://github.com/your-repo/project --dont-wait --class-id <your-env-class-id>)

# Run a task
TASK_ID=$(ona automations task start build-and-test --environment-id $ENV_ID)

# Stream logs
ona automations task logs $TASK_ID --environment-id $ENV_ID

# Check result and clean up
TASK_STATUS=$(ona automations task get $TASK_ID --environment-id $ENV_ID -o json | jq -r .status)

if [ "$TASK_STATUS" = "succeeded" ]; then
    ona environment delete $ENV_ID
else
    echo "Task failed. Environment left for inspection."
fi
```

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

### Clear Dotfiles Configuration

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

Resets the dotfiles configuration, effectively clearing the current setup.

```bash
ona user dotfiles set
```

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

### Manage Prebuilds and Warm Pools

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

List, trigger, create, get, update, and delete prebuilds and warm pools. Requires project admin privileges for warm pool creation.

```bash
# List prebuilds for a project
ona prebuild list --project-id <project-id>
```

```bash
# Trigger a prebuild
ona prebuild trigger <project-id>
```

```bash
# List all warm pools in the organization
ona prebuild warm-pool list
```

```bash
# List warm pools for a specific project
ona prebuild warm-pool list --project-id <project-id>
```

```bash
# Create a warm pool (project admin required)
ona prebuild warm-pool create <project-id> --environment-class-id <class-id> --min-size 1 --max-size 2
```

```bash
# Get warm pool details
ona prebuild warm-pool get <warm-pool-id>
```

```bash
# Update pool scaling bounds
ona prebuild warm-pool update <warm-pool-id> --min-size 1 --max-size 3
```

```bash
# Delete a warm pool
ona prebuild warm-pool delete <warm-pool-id>
```

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

### Prebuilds

Source: https://ona.com/docs/ona/api-reference

Manage prebuilds for projects to enable faster environment startup times. Prebuilds create snapshots of environments that can be used to provision new environments quickly.

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

### Description
Cancels an ongoing prebuild process.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/CancelPrebuild

## POST /gitpod.v1.PrebuildService/CreatePrebuild

### Description
Creates a new prebuild for a project.

### Method
POST

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

## POST /gitpod.v1.PrebuildService/CreatePrebuildLogsToken

### Description
Generates a token for accessing prebuild logs.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/CreatePrebuildLogsToken

## POST /gitpod.v1.PrebuildService/CreateWarmPool

### Description
Creates a warm pool for prebuilds.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/CreateWarmPool

## POST /gitpod.v1.PrebuildService/DeletePrebuild

### Description
Deletes a prebuild.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/DeletePrebuild

## POST /gitpod.v1.PrebuildService/DeleteWarmPool

### Description
Deletes a warm pool.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/DeleteWarmPool

## POST /gitpod.v1.PrebuildService/ListPrebuilds

### Description
Lists all prebuilds for a project.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/ListPrebuilds

## POST /gitpod.v1.PrebuildService/ListWarmPools

### Description
Lists all warm pools.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/ListWarmPools

## POST /gitpod.v1.PrebuildService/GetPrebuild

### Description
Retrieves a specific prebuild.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/GetPrebuild

## POST /gitpod.v1.PrebuildService/GetWarmPool

### Description
Retrieves a specific warm pool.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/GetWarmPool

## POST /gitpod.v1.PrebuildService/UpdateWarmPool

### Description
Updates an existing warm pool.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/UpdateWarmPool
```

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

### Get Webhook Signing Secret

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

Retrieve the signing secret for a specific webhook using its ID.

```bash
ona webhook secret get <id>
```

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

### AGENTS.md Example for System Guidance

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

This markdown file serves as a readme for agents, providing essential information about system architecture, feature development conventions, commit message standards, Go language conventions, and code generation practices. It uses capitalization for emphasis on critical rules.

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

## Feature work
- use feature branches from main for pushing work following this naming pattern:
  - [2-3 initials from git config user.name]/[numeric-part-of-issue-ID]-[2-3 word shorthand]
  - should not be more than 24 characters total
IMPORTANT: Always run git config user.name first to get the actual name

## Commit messages
- Follow Conventional Commits: <type>[scope]: <description>
- Types: feat, fix, build, chore, ci, docs, style, refactor, perf, test

## Go Conventions
- Accept interfaces, return concrete types
- Always wrap errors with fmt.Errorf and %w
- Every Ent query must use .Select() to fetch only needed columns

## Code generation
- ALWAYS use leeway scripts to generate code, e.g. `leeway run api/def:generate`
  instead of running `buf generate` directly.
```
Tokens:
Raw