Skip to main content
This guide walks you from “I have an Ona account” to “I have a scheduled Automation running.” By the end, you will have a project, a reproducible environment, and an Automation that runs on a schedule and delivers merge-ready pull requests.

Prerequisites

Before you start:
  • An Ona account on a Core or Enterprise plan
  • At least one runner in your organization
  • A repository with code you want to automate against

Step 1: Create a project

A project connects your repository to a runner. It is the blueprint for every environment and every Automation run. If you already have a project for your repository, skip to Step 2. Follow the Create your first project guide to set one up. You need a repository URL, a project name, and at least one environment class.

Step 2: Make your repository AI-ready

For Automations to work reliably, the environment must be reproducible. Every Automation run starts a fresh environment from your configuration. If the environment does not have your tools, dependencies, and services, the Automation cannot reliably clone, build, test, and iterate. Two files make your repository AI-ready:

devcontainer.json

Defines the base image, language runtimes, tools, and VS Code extensions. Place it at .devcontainer/devcontainer.json in your repository. Minimal example:
{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {}
  }
}
See Set up your first environment for the full configuration reference.

automations.yaml

Defines startup tasks (install dependencies, seed databases) and long-running services (databases, servers). Place it at .devcontainer/automations.yaml in your repository. Minimal example:
tasks:
  install:
    name: Install dependencies
    command: npm ci
    triggeredBy:
      - postDevcontainerStart
See Tasks and Services for the full configuration reference.

Shortcut: use an Automation to generate your environment config

Bootstrap both files by creating an Automation with a single Prompt step. Create a new Automation, add one Prompt step with the following text, select your project, and run it. The Automation analyzes your repository and generates devcontainer.json and automations.yaml.
Create a high-quality, fully working "development environment as code" configuration for the current environment.

The setup must work for:
  - Ona (Gitpod Flex) development environments, which use DevContainer configurations.
Do not confuse this with Gitpod Classic (Gitpod Dedicated), which uses .gitpod.yml.
  - All Git repositories mounted under the DevContainer workspace.

Terminology
  - apps: Source code intended to be built and shipped.
  - dev tool: Any tool used for compiling, building, publishing, testing, profiling, debugging, or accessing an app's infrastructure.

Required Process
  1. Read the documentation (see Allowed Sources) to fully understand:
    - Ona automations, secrets, environment variables, CLI, and prebuilds.
    - DevContainer fundamentals and how they integrate with Ona and VS Code.
  2. Analyze the source code and identify:
    - Documentation on dev setup or contribution guidelines.
    - Configuration files for containers, IDEs, build tools, environment variables, etc.
  3. Update all necessary files, including:
    - devcontainer.json
    - Ona automations (tasks and services)
    - Any other files required to meet the Success Criteria.
  4. Run the Acceptance Tests for all code you have created and iterate until the last run of every Acceptance Test has been successful.
  5. Do not create any documentation files.

Success Criteria
  - The DevContainer includes all tools needed to work with any file in any repo in this environment.
  - Ona automation services exist for every service required or recommended to run any app in this environment.
  - Ona automation services exist for every app, for the standard or documented configurations.
  - Ona automation tasks exist for all standard or documented development workflows for this repo.
  - If an app exposes a TCP port, the DevContainer must forward it.
  - If an app exposes an HTTP/HTTPS port, the corresponding Ona automation service must expose it by running "gitpod env port open" before starting the app.
  - The DevContainer must install all VS Code extensions necessary to work effectively with the files and services in this environment.

Acceptance Tests
  - The command "gitpod auto update <filename>" succeeds
  - The command "gitpod env devcontainer validate" succeeds
  - The DevContainer rebuilds successfully.
  - All installed tools launch successfully and are available in the correct version
  - Ona automation tasks start and finish successfully.
  - Ona automation services successfully reach the state "ready".
  - Apps exposed via Ona port respond successfully when curl'ing the port.

Allowed Sources
  - Ona documentation: automations, secrets, environment variables, CLI, prebuilds, DevContainers
    https://ona.com/docs/llms.txt
  - DevContainer documentation: https://containers.dev/
  - DevContainers in VS Code: https://code.visualstudio.com/docs/devcontainers/containers
  - DevContainer base images: https://hub.docker.com/r/microsoft/devcontainers
  - VS Code extensions:
    - https://marketplace.visualstudio.com/vscode
    - https://open-vsx.org/
  - Any publicly available DevContainer features
  - Anything installable within a Dockerfile

Verify your environment

Start an environment from your project. Run your test suite. If everything passes interactively, it will work for Automations.

Step 3: (Optional) Configure integrations

Integrations give Automations context from external tools. For example, the Sentry integration lets Automations read error data, and the Linear integration lets them read and update issues. Configure integrations in Settings > Integrations. See the setup guides for Sentry, Linear, Notion, and Atlassian.

Step 4: (Optional) Create a service account

If you plan to run Automations on a schedule or share them with your team, create a service account. Commits, PRs, and comments will appear under the service account identity instead of your personal account.

Step 5: Create your first Automation

  1. Go to Automations in Ona.
  2. Click New Automation.
Automations page with New Automation button
  1. Choose Start from scratch or pick a template.
New Automation dialog showing start options

Configure basics

  • Name: a descriptive name (e.g., “Weekly dependency updates”)
  • Description: what the Automation does
  • Run as: your user or a service account
Basic configuration form

Add steps

Steps run in sequence. Example for a dependency update Automation: Step 1: Prompt
Update all dependencies to their latest compatible versions.
Run the test suite and fix any breaking changes.
Step 2: Command
npm test
Step 3: Pull Request Create a PR with the changes for review. Steps configuration

Set guardrails

Guardrails prevent runaway executions:
  • Max concurrent: 5 (for testing)
  • Max total: 20
Increase these once you are confident the Automation works.

Choose a trigger

For your first run, select Manual to test immediately.
TriggerBest for
ManualOne-time migrations, testing Automations
Pull RequestCode review, security checks, test runs
Time-basedScheduled maintenance, recurring updates

Save

Click Save.

Step 6: Run manually and verify

  1. Open the Automation.
  2. Select target repositories.
  3. Click Run.
Watch the Automation execute. It starts an environment, runs your steps, and creates pull requests. Review the output and the PRs it created. Start manual. Run the Automation a few times, review the results, and adjust steps as needed. Build confidence before scheduling.

Step 7: Schedule it

Once you trust the output, switch the trigger to Time-based:
  1. Open the Automation settings.
  2. Change the trigger to Time-based.
  3. Set a cron schedule (e.g., 0 9 * * 1-5 for weekday mornings at 9 AM UTC).
  4. Save.
The Automation now runs on schedule. You review merge-ready PRs instead of doing the work yourself. This is the pattern from the blog: start manual, gain confidence, then schedule.

What’s next