Creating an Automation

How to set up a new automation

Create automations to execute workflows across your repositories—whether repeatable tasks or large-scale one-time changes. Define the automation once, then trigger it manually, on a schedule, or from pull request events.

Access the Automations page

1. Open Ona and navigate to Automations in the left panel
2. Click New Automation in the top right corner

You can also access automations directly at https://app.gitpod.io/automations

Choose a starting point

Select how to create your automation:

• Start from scratch - Build a custom automation from the ground up
• Use a common use case - Start with a pre-configured template (e.g., automated Dev Container setup)

Common use cases pre-populate prompts and steps for specific workflows. You can customize them after creation.

Configure basic settings

Fill in the automation details:

Name and description

• Name - Short, descriptive name for the automation (e.g., “Weekly dependency updates”)
• Description - Explain what the automation does

Run as

Choose who executes the automation:

• Your user - Use your own account and permissions

  • Best for: Manual automations you want to own and control
  • Example: One-time migrations or personal workflows

• Service account - Use a dedicated automation account

  • Best for: Event-driven automations (pull request triggers) and time-based automations (scheduled jobs)
  • Example: Automated code reviews, scheduled dependency updates, or nightly builds

See Service Accounts for setup details.

Select trigger type

Choose when the automation runs. See the trigger-specific sections below for detailed configuration:

• Manual - Run on demand for selected projects or repositories
• Pull Request - Trigger automatically on pull request events
• Time-based - Run on a schedule (cron)

Configure guardrails

Set limits to control automation execution and manage costs. These guardrails prevent runaway executions and help you control resource usage.

• Max concurrent executions - Maximum automations running at the same time (default: 10)
• Max total executions - Maximum total executions allowed (default: 100)

Why these limits matter:

• Prevent accidental large-scale runs that could impact your systems
• Manage resource allocation across your organization

Recommended values:

• Small-scale testing (1-10 repositories): Set concurrent to 5, total to 20
• Team-level automation (10-50 repositories): Use defaults (10 concurrent, 100 total)
• Organization-wide rollout (50+ repositories): Set concurrent to 20-50, total to 500+

When limits are reached the automation will stop. You can then adjust limits and re-run if needed.

Learn more about Guardrails for automation safety controls.

Steps

What are steps

Steps are executed in sequence. Each step runs in the same environment, allowing steps to build on previous work.

Steps can be:

• Prompts - Natural language instructions for Ona Agent
• Shell scripts - Direct commands to execute
• Pull Request steps - Automated pull request creation with customizable settings

What are prompts

Prompts are instructions written in natural language that tell Ona Agent what to do. The agent interprets the prompt and acts accordingly.

When to use prompts:

• Complex tasks requiring decision-making (e.g., “analyze code and suggest improvements”)
• Tasks that vary by repository structure
• When you want the agent to adapt to different scenarios

Example prompt:

Update all dependencies to their latest compatible versions, run tests, and provide a summary of your changes.

What are shell scripts

Shell scripts are executed in the automation environment by the agent. Use them for deterministic operations.

When to use shell scripts:

• When you need deterministic behaviour
• When you need precise control over what’s executed in the environment

Example shell script:

echo "Starting dependency update"
npm update
npm test

Prompt vs Script guidance:

• Use prompts for flexible, context-aware tasks
• Use scripts for predictable, repeatable tasks
• Combine both: scripts for setup/validation, prompts for intelligent changes

What are pull request steps

Pull request steps automatically create pull requests with your changes. Use them to submit automation results for review.

When to use PR steps:

• After making code changes that need review
• To create standardized PRs with consistent titles and descriptions
• When you want automation to handle the entire PR creation process

Example: Add a PR step after running tests to automatically create a pull request with test results and change summary.

Defining multi-step workflows

Multi-step workflows let you break complex tasks into manageable pieces, with each step building on the previous one.

Why use multiple steps:

• Validation - Run tests between changes to catch issues early
• Clarity - Separate concerns (e.g., update code, then test, then create PR)
• Debugging - Identify exactly which step failed
• Reusability - Mix and match prompts, scripts, and PR steps

Add multiple steps to create complex workflows:

1. Click Add Step
2. Choose the step type
3. Fill out the step details
4. Repeat to add more steps

Steps execute in order from top to bottom. Use the drag-and-drop functionality to reorder steps as needed.

Passing data between steps

Steps run in the same environment and Ona Agent maintains context across steps. This means:

• Files created by previous steps are accessible
• Environment variables set earlier persist
• Shell script outputs and results are available
• The agent remembers previous prompts and their results

Example workflow:

1. Step 1 (Prompt): “Upgrade all dependencies to their latest versions”
2. Step 2 (Shell Script): npm test (verify changes work)
3. Step 3 (PR Step): Create pull request with summary of changes and test results

Example configurations

Dependency upgrade with pull request:

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

Documentation update with pull request:

Step 1 (Prompt): Update the README.md to include the new API endpoints from the OpenAPI spec
Step 2 (PR Step): Create pull request with documentation changes

Large-scale refactoring:

Step 1 (Prompt): Refactor all API calls to use the new authentication library
Step 2 (Shell Script): npm run lint && npm test
Step 3 (PR Step): Create pull request summarizing refactoring changes and test results

Save the automation

Click Save to create the automation.

Editing automations: You can edit any automation at any time by opening it from the automations list and clicking Edit. All settings—including steps, triggers, guardrails, and targets—can be modified after creation.

Webhook configuration for pull request triggers is available after saving. See Pull Request Triggers for details.

Next steps

Configure your trigger type:

• Manual Triggers
• Pull Request Triggers
• Time-based Triggers

Or learn how to:

• Run an Automation
• Review Results