Automations
An automation starts a session from a prompt, workflow, or bot according to a manual, scheduled, loop, or external trigger.
What an automation runs
The run configuration determines the session behavior.
| Session type | Supported content |
|---|---|
| Develop | Inline prompt or workflow for task-focused work. |
| Chat | Inline prompt for a persistent conversation. |
| Bot | A conversation using the selected bot. |
Select a model, one starting branch per repository, and the session options required by the task. Recurring and loop runs can use the previous run time as context for relative instructions.
Trigger types
A trigger determines when a run starts.
| Type | Behavior |
|---|---|
| Manual | Starts only when an operator selects Run Now. |
| One-Time | Starts once at the configured date and time. |
| Recurring | Uses a five-field cron expression, supported schedule macro, or interval in the selected IANA timezone. |
| Loop | Starts another run after the previous session completes. |
| HTTP Trigger | Starts when an external system calls the generated webhook. |
Recurring intervals support seconds, minutes, hours, and days, with a minimum interval of 30 seconds. Supported macros are @hourly, @daily, @weekly, @monthly, and @yearly.
Use relative dates in recurring prompts. Fixed dates and lookback periods that do not match the cadence can produce stale or duplicate work; creation and editing may display a non-blocking warning.
Run options
Run options control completion and recovery behavior.
| Option | Behavior |
|---|---|
| Auto-Complete Session | Marks the session done after successful execution. |
| Complete only if no file changes | Leaves a Develop session open when file changes require review. |
| Auto-Execute Missed Runs on Startup | Runs a missed recurring occurrence after service recovery. |
| Workflow Parameters | Supplies initial values to the selected workflow. |
| Session Mode Toggles | Enables configured review, verification, test, documentation, or edge-case behavior. |
Use Run Now to validate any automation without changing its schedule.
HTTP triggers
An HTTP trigger provides a generated webhook URL and secret token for CI or external systems.
- Create an HTTP Trigger automation.
- Copy the generated integration details immediately.
- Store the token in the caller's secret store.
- Prefer the authenticated request form shown in the UI so the token is not written to URL logs or browser history.
- Send query or JSON values only for parameters the automation expects.
Request values override stored workflow defaults with the same name. Inline prompts can reference request values using the placeholder format shown in the automation editor.
The response identifies whether a run started and, when applicable, the created session. A trigger is rejected when authentication is invalid, input is too large or malformed, or the automation already has a run that blocks concurrent execution.
Regenerating the token invalidates the previous token immediately. Rotate it after suspected disclosure and update every caller before its next run.
HTTP-triggered automations do not use schedules, missed-run recovery, or background schedule checks.
Execution history
Execution history is the operator record for each attempted run.
Review the trigger source, start time, status, linked session, pull request link when available, and failure message. Open the linked session for agent output, hook failures, verification results, and pending approval.
Failure handling
Failure controls prevent a repeatedly failing automation from consuming capacity indefinitely.
Repeated failures can disable an automation and notify its owner. After correction, run it manually, verify success in execution history, and then re-enable the schedule or loop.
Permissions
Permissions separate viewing from configuration and execution.
| Permission | Capability |
|---|---|
automations.view_own | View automations and history the user owns. |
automations.view_all | View all automations and history across owners. |
automations.manage | Create, edit, enable, disable, delete, and run the user's own automations. |
automations.manage_all | Create, edit, enable, disable, delete, and run any automation. |
Running an automation manually (Run Now) requires a manage permission; there is no separate execute permission. HTTP callers authenticate with the automation token rather than an interactive user account. Treat possession of that token as permission to start the configured work.
Troubleshooting
These checks cover common automation incidents.
| Symptom | Check |
|---|---|
| Scheduled run did not start | Confirm the automation is enabled, timezone and next run are correct, and the session host has capacity. |
| Missed run was not recovered | Confirm Auto-Execute Missed Runs on Startup is enabled and review execution history for an existing run. |
| Loop stopped | Open the last execution and session, correct the failure, test with Run Now, then re-enable. |
| Workflow parameters are missing | Match request or stored parameter names to the workflow's initial aliases. |
| HTTP trigger is unauthorized | Replace the caller's token with the current generated token and verify its secret handling. |
| HTTP trigger reports a conflict | Open the linked active session and wait for or complete it before retrying. |
| Session remains open | Check approval state, file changes, and Complete only if no file changes. |