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:
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:
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 generatesdevcontainer.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, 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
- Go to Automations in Ona.
- Click New Automation.

- Choose Start from scratch or pick a template.

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

Add steps
Steps run in sequence. Example for a dependency update Automation: Step 1: Prompt
Set guardrails
Guardrails prevent runaway executions:- Max concurrent: 5 (for testing)
- Max total: 20
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 |
| Time-based | Scheduled maintenance, recurring updates |
Save
Click Save.Step 6: Run manually and verify
- Open the Automation.
- Select target repositories.
- Click Run.
Step 7: Schedule it
Once you trust the output, switch the trigger to Time-based:- Open the Automation settings.
- Change the trigger to Time-based.
- Set a cron schedule (e.g.,
0 9 * * 1-5for weekday mornings at 9 AM UTC). - Save.
What’s next
- Automations in practice for real-world examples (Sentry triage, backlog picker, Knip cleanup, CVE remediation, migrations)
- 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
- Automations overview for the complete reference