Automation Manager

Automation Manager

Automations have two representations that must stay in sync:

1. YAML file in .ona/automations/<name>.yaml — version-controlled source of truth.
2. Live registration in Ona — the runtime configuration that actually triggers executions.

Editing only the YAML does nothing. Registering only via CLI loses version history. Every change must update both.

Authentication

The environment principal cannot manage automations. Authenticate with the user PAT:

ona login --token "$ONA_PAT"

Restore the environment context when done:

ona config context use environment

Creating a new automation

1. Generate the example syntax for reference:

   ona ai automation create --example
   

2. Create the YAML file at .ona/automations/<name>.yaml. Follow the structure of existing automations in that directory. Required fields: name, description, triggers, action.limits, action.steps.

3. Register it:

   ona login --token "$ONA_PAT"
   ona ai automation create .ona/automations/<name>.yaml
   

   The CLI prints the new automation ID.

4. Add the new entry to references/registry.md with the YAML filename, name, and ID.

5. Restore context:

   ona config context use environment
   

6. Commit both the YAML file and the updated registry.

Updating an existing automation

1. Look up the automation ID in references/registry.md.

2. Edit the YAML file.

3. Push the update to Ona:

   ona login --token "$ONA_PAT"
   ona ai automation update <automation-id> .ona/automations/<name>.yaml
   

4. Verify the update took effect:

   ona ai automation get <automation-id> -o json | jq '.[0].spec.triggers'
   

5. Restore context:

   ona config context use environment
   

6. Commit the YAML change.

Deleting an automation

1. Look up the automation ID in references/registry.md.

2. Delete from Ona:

   ona login --token "$ONA_PAT"
   ona ai automation delete <automation-id>
   

3. Delete the YAML file.

4. Remove the row from references/registry.md.

5. Restore context and commit.

Auditing drift

Compare YAML files against live registrations to find mismatches.

1. List live automations:

   ona login --token "$ONA_PAT"
   ona ai automation list -o json | jq '[.[] | {id: .id, name: .metadata.name}]'
   

2. List YAML files:

   ls .ona/automations/*.yaml
   

3. Check for:

   • YAML files with no matching live automation (unregistered).
   • Live automations with no matching YAML file (untracked).
   • Name mismatches between YAML name: field and live metadata.name.

4. For each unregistered YAML: run ona ai automation create.

5. For each untracked live automation: either create the YAML or delete the live registration.

6. Update references/registry.md with any changes.

Trigger design rules

These rules prevent the race conditions that caused duplicate PRs (#45/#46, #40/#41):

• One trigger type per automation. Use either cron OR webhook, not both. The cron alone is sufficient — a 10-minute delay after a merge is acceptable.
• maxParallel: 1 on all automations. This is necessary but not sufficient (the platform has a TOCTOU window during environment startup).
• Prompt-level guards are defense-in-depth, not primary protection. The prompt should check for existing work (open PRs, in-progress labels) but cannot guarantee mutual exclusion.

YAML structure reference

name: Human-readable name
description: One-line description of what the automation does.
triggers:
    - context:
        projects:
            projectIds:
                - 019d8bf4-1ded-7317-be2f-555e8fb55ff9
      time:
        cronExpression: "*/10 * * * *"
    - context:
        projects:
            projectIds:
                - 019d8bf4-1ded-7317-be2f-555e8fb55ff9
      manual: {}
action:
    limits:
        maxParallel: 1
        maxTotal: 50
    steps:
        - agent:
            prompt: |
                Your prompt here.

Trigger types (use only one per automation, plus manual):

• time.cronExpression — cron schedule
• pullRequest.events — webhook events (avoid combining with cron)
• manual — always include for manual runs

Reference files

• references/registry.md — Read when you need to look up an automation ID or check which automations are registered.