Documentation Index
Fetch the complete documentation index at: https://ona.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
You’ve learned how to work with agents interactively. Now let’s explore Ona Automations: proactive background agents that combine AI prompts with deterministic commands in trigger-based workflows, from routine maintenance to large-scale refactoring.
What are Ona Automations
Automations are proactive background agents running in the cloud. They combine AI prompts with deterministic commands in trigger-based, closed-loop workflows that deliver merge-ready pull requests. Instead of manually triggering agents in individual environments, automations execute across hundreds of repositories automatically.
Each automation combines:
- Steps - Prompts, shell scripts, pull request steps, or report steps
- Triggers - Manual, pull request events, time-based schedules, or webhooks
- Targets - Projects or repositories to run against
- Guardrails - Limits to control execution
How automations work
- Trigger - Run manually, on PR events, on a schedule, or via webhook
- Execute - Ona clones, branches, installs, builds, tests, iterates, commits, pushes, and opens a PR. The same loop a human engineer runs, except Automations can do it across hundreds of repos in parallel
- Review - Inspect outputs, logs, and linked PRs. Approve and merge when satisfied
Every Automation runs in a fully configured environment defined by devcontainer.json and automations.yaml. Dependencies install, services start, tools are available. Not a minimal CI runner, but a full development environment.
Key terms
- Automation - A workflow definition that executes changes
- Execution - A single run of an automation
- Action - The result of running on one repository (one execution creates multiple actions)
- Step - An individual operation (prompt, shell script, PR creation, or report)
Creating your first automation
Access the Automations page
- Open Ona and navigate to Automations in the left panel
- Click + Automation in the top right corner
- Choose Start from scratch or select a pre-configured template from the dropdown
You can also access automations directly at https://app.ona.com/automations
Click the first step in the automation editor to configure its details. To rename the automation, click the three-dot menu (⋯) in the top right corner.
- Name - Short, descriptive name (e.g., “Weekly dependency updates”)
- Description - Explain what the automation does
- Run as - Choose your user or a service account
When to use service accounts:
- Event-driven automations (pull request triggers)
- Time-based automations (scheduled jobs)
- Team-wide automations where you want activity tracked separately
The Runs on section defines which projects or repositories the automation targets when it executes:
- Projects - Select one or more projects. The automation runs on all repositories within them. Best for repetitive tasks on known repositories.
- Repositories - Use a search query to match repositories by name. Best for large-scale migrations across many targets. Partial matches work across owner and repository names.
For this exercise, feel free to select the project you created during Setup.
Automations work best with projects. A project provides the Dev Container configuration, dependencies, and environment settings that your Automation runs against. We recommend setting up a project before creating Automations. Choose a trigger type
- Manual - Run on demand. Best for one-time migrations, testing automations, or changes requiring human judgment on timing.
- Pull Request - Trigger on PR events. Best for automated code reviews, security scanning, or documentation updates.
- Time-based - Run on a schedule (hourly, daily, weekly, monthly). Best for dependency updates, nightly security scans, or compliance checks.
Add steps
Steps execute in sequence within the same environment. Each step can access files, environment variables, and context from previous steps.
| Step type | Use when |
|---|
| Prompt | Flexible tasks requiring agent judgment: “analyze and improve”, “update based on context” |
| Shell script | Deterministic operations: npm test, docker build |
| Pull request | Submit changes for review after making modifications |
| Report | Extract structured data from the execution: test coverage, dependency counts, build metrics |
Update all dependencies to their latest compatible versions, run tests, and provide a summary of your changes.
Example: Multi-step automation
A typical automation might have:
Step 1 (Prompt): Upgrade all dependencies to their latest versions
Step 2 (Shell script): npm test
Step 3 (PR Step): Create pull request with summary of dependency upgrades and test results
Set guardrails
Control execution limits to prevent automations from running excessively:
- Max concurrent executions - How many run simultaneously
- Max total executions - Maximum total runs allowed
Maximum values depend on your plan:
| Limit | Core | Enterprise |
|---|
| Max concurrent | 10 | 25 |
| Max total | 50 | 100 |
| Stage | Concurrent | Total |
|---|
| Initial test | 5 | 10 |
| Team validation | 10 | 50 |
| Full rollout | 25 | 100 |
Practical scenario 1: README standardization
Ensure every repository has consistent documentation.
The automation
Name: README and Backstage YAML maintenance
Trigger: Manual
Target: The project you created during Setup
Steps:
Step 1 (Prompt):
Analyze this repository and ensure it has:
1. A comprehensive README.md with:
- Project description
- Setup instructions
- Usage examples
- Contributing guidelines
2. A backstage.yaml file with correct metadata
Follow the documentation standards in our org-wide AGENTS.md.
Update or create files as needed.
Step 2 (PR Step, optional):
Create pull request with documentation updates
Why this works
- Eliminates documentation toil for engineers
- Ensures consistent structure across all repositories
- Platform teams gain control over documentation quality
- Changes go through PR review before merging
Practical scenario 2: Automated security review
Catch security issues automatically when code changes.
The automation
Name: Security code review
Trigger: Pull Request (events: Opened, Updated)
Target: The project you created during Setup
Steps:
Step 1 (Prompt):
Review the code changes in this pull request for security vulnerabilities:
1. Check for:
- SQL injection
- XSS vulnerabilities
- Authentication/authorization issues
- Secret exposure
- Insecure dependencies
2. Post a detailed review comment on the PR with:
- Issues found (with file and line numbers)
- Severity (Critical/High/Medium/Low)
- How to fix each issue
If no issues found, post a comment confirming the review passed.
Why this works
- Immediate security feedback on every code change
- No waiting for manual security review
- Consistent review criteria across all repositories
- Issues caught before code reaches main branch
Practical scenario 3: Weekly dependency updates
Keep dependencies current automatically.
The automation
Name: Weekly dependency updates
Trigger: Time-based (Weekly, Monday at 2 AM)
Target: The project you created during Setup
Steps:
Step 1 (Prompt):
Check for outdated dependencies and update them:
1. Run the appropriate command for this project type (npm outdated, pip list --outdated, etc.)
2. Update dependencies to latest compatible versions
3. Run the test suite
4. If tests fail, revert the problematic update and try the next minor version
Step 2 (Shell script):
npm test || pytest || go test ./...
Step 3 (PR Step, optional):
Create pull request with:
- Title: "chore: weekly dependency updates"
- Body: List of updated packages with version changes and any notes about compatibility
Why this works
- Reclaim engineering hours spent on CVE remediation
- Automated fixes handle version bumps and breaking changes
- Tests run before PR is created
- Fresh updates ready for review every Monday
Running and monitoring automations
Starting an automation
- Open the Automation (or use the three-dot menu from the list)
- Click Run
- Confirm target repositories/projects
Monitoring progress
The run details page shows real-time execution status:
Action statuses:
- Running - Currently executing
- Pending - Queued
- Completed - Finished successfully
- Failed - Encountered errors
Click any action to view its session logs: each step, agent responses, command outputs, and errors.
Stopping executions
- Cancel individual action: Three-dot menu next to an action > Cancel
- Cancel entire run: Click Cancel on the run details page to stop all actions
Running actions stop immediately. Pending actions are skipped.
Reviewing results
After completion:
- View the execution summary (completed, failed, canceled counts)
- Click individual actions to review logs
- Check your SCM (GitHub/GitLab) for pull requests created by the Automation
- Review and merge each PR independently
Best practices
Do’s
- Start small - Test on 1-2 repositories before scaling
- Use service accounts - Track automation activity separately from human work
- Set conservative guardrails - Prevent accidental large-scale runs
- Write specific prompts - Include file paths, patterns to follow, verification steps
- Request verification - Have automations run tests before creating PRs
- Review PRs - Always inspect automation-created changes before merging
Don’ts
- Don’t skip testing - Always verify on a few repos first
- Don’t set unlimited guardrails - Even trusted automations should have limits
- Don’t merge blindly - Automation PRs need human review
- Don’t over-automate - Some changes need human judgment
When to use which trigger
| Trigger | Best for |
|---|
| Manual | One-time migrations, testing automations, changes needing timing judgment |
| Pull Request | Code review, security scanning, documentation validation |
| Time-based | Dependency updates, nightly scans, compliance reports |
Troubleshooting
Automation not starting
- Check guardrails, you may have hit the limit
- Verify you have access to target repositories
- For PR triggers, confirm webhook is configured correctly
Actions failing
- Click the failed action to see session logs
- Check if the prompt is too vague; be specific
- Verify dependencies are installed (use Dev Container for consistent setup)
No pull requests created
- Check if the automation found changes to make
- Verify the PR step is configured
- Check SCM permissions for the service account
Webhook not triggering
- Verify webhook URL and secret in SCM settings
- Check that the correct events are selected
- Test with a new PR to trigger the webhook
Automation too slow
- Break into smaller, targeted automations
- Reduce concurrent limit if hitting resource constraints
- Use shell scripts for deterministic tasks, prompts for intelligent decisions
What you’ve learned
You now know how to:
- Create automations with prompts, shell scripts, and PR steps
- Configure triggers for manual, event-driven, or scheduled execution
- Set guardrails to control automation execution safely
- Monitor progress and review results in real-time
- Scale safely by starting small and verifying before expanding
Automations transform manual, repetitive work into automated workflows that run at organizational scale.
Next up: Make Ona Your Own, personalize your environments with dotfiles, user secrets, and IDE settings. Or return to Workshop Overview to review what you’ve learned.
