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

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.
Automations page with suggested templates

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
Step 2: Command
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. 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. Select Every weekday and set the time, for example 9:00 AM UTC for weekday mornings. Choose Every day instead if the Automation should also run on weekends.
  4. Save.
The Automation now runs on schedule. You review merge-ready PRs instead of doing the work yourself.

What’s next