Create your first Automation

Go from zero to a scheduled Automation: set up a project, make your repository AI-ready, and run your first closed-loop workflow.

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 development environments, which use DevContainer configurations.
  - 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 "ona 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 "ona auto update <filename>" succeeds
  - The command "ona 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, Granola, and Atlassian.

Step 4: (Optional, Enterprise) 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. Service account executors require an Enterprise plan.

Step 5: Create your first Automation

1. Go to Automations in Ona.
2. Click New and choose Start from scratch or pick a template from the suggestions panel.

Name and description

To set or change the name and description, open the ⋯ menu and select Rename. A dialog opens where you can edit both fields.

Set the executor

The Run Automation as field is in the trigger configuration panel. Click the trigger node to open the side panel — the executor selector is at the bottom.

• Your user: Automations run under your identity. Commits and PRs appear as you.
• Service account (Enterprise only): Automations run under a shared service account identity.

Service account executors are an Enterprise feature. On Core plans, Automations run as your user.

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.

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.

Trigger	Best for
Manual	One-time migrations, testing Automations
Pull Request	Code review, security checks, test runs
Scheduled	Recurring maintenance, dependency updates

Click Save to create the Automation.

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 Scheduled:

1. Open the Automation settings.
2. Change the trigger to Scheduled.
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.

What’s next

• Automations in practice for real-world examples
• Configure Automations for the full settings reference
• Pull request triggers for Automations that run on PR events
• Time-based triggers for scheduling options
• Guardrails for safety controls
• Service accounts for team-wide Automations