Automations
An automation starts a session from saved instructions, or creates a fresh pending ticket from saved content, on a schedule, a loop, a manual run, or an external HTTP call.
What an automation runs
The session type and execution source determine what each run does.
| Session type | Supported content |
|---|---|
| Develop | Inline prompt, workflow, or Create Ticket (scheduled ticket creation). |
| Chat | Inline prompt for a persistent conversation. |
| Bot | A conversation with the selected bot, started with a required Initial Message. |
Select a model, one starting branch per repository, and the session options required by the task. Every automation session receives the previous run time as context, so prompts can use relative instructions such as "changes since the last run".
Inline prompts can reference caller values with {{name}} placeholders and session values with the workflow automatic parameters such as $session-url. A Develop inline prompt can also run as a Ralph Loop with Run Inline Prompt as a Loop.
Scheduled ticket creation
Scheduled ticket creation saves a title, description, tags, developer assignment, and QA assignment, then creates one new pending ticket for each eligible occurrence. It does not start an agent session, alter an older ticket, or queue the new ticket automatically.
- Choose the Develop session type, then Create Ticket as the execution source.
- Select a one-time or recurring schedule and timezone. Review the upcoming-occurrence preview.
- Enter the saved ticket content and optional assignments.
- Optionally set an end date or maximum number of tickets.
- Save the automation. Open History to view each generated ticket and its scheduled occurrence.
The automation page shows the next occurrence, successful creation count, and the reason a schedule is paused, stopped, or failing. If a saved assignee no longer belongs to the workspace, no ticket is created and the schedule stops with the validation error. Edit the assignment before enabling it again. Ticket-creation automations run only from their schedule; Run Now is not available.
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. A time up to 2 minutes in the past is accepted and runs immediately. |
| Recurring | Uses a five-field cron expression, a schedule macro, or an interval, evaluated in the selected timezone. |
| Loop | Starts the next run after the previous session finishes. |
| HTTP Trigger | Starts when an external system calls the generated webhook. See HTTP triggers. |
Recurring schedules
Recurring schedules accept three forms.
| Form | Example | Notes |
|---|---|---|
| Cron (5-field) | 0 9 * * 1-5 | Minute, hour, day of month, month, day of week. |
| Macro | @daily | @hourly, @daily, @midnight, @weekly, @monthly, @yearly, @annually. |
| Interval | @every 15m | @every <N>s, m, h, or d; enter through Custom. Minimum 30 seconds. Intervals ignore the timezone. |
The timezone is selected from a list of common zones. Schedules are checked once per minute, so an interval shorter than a minute does not run more often than once per minute.
Use relative dates in recurring prompts. Fixed dates and lookback periods that do not match the cadence can produce stale or duplicate work; creating or editing such a prompt displays a non-blocking warning.
Loop behavior
A Loop starts its next run when the previous session reaches Done. Loops do not offer Auto Complete Session, so each session must be completed (manually, by a workflow, or by the agent). A Develop loop waits for the previous run's pull request to be merged or closed before starting again. After a failed run, the next attempt starts after about one minute. Canceling a loop's session disables the loop.
Run options
Run options control completion, concurrency, ownership, and recovery.
| Option | Behavior |
|---|---|
| Auto Complete Session | Marks the session done after successful execution. Not available for Loop. |
| Complete only if no file changes | Develop only. Leaves the session open when file changes require review. |
| Auto Archive | Hides the session from the sidebar unless it is waiting for your answer. |
| Auto Execute Missed Run | Runs a missed recurring or one-time occurrence after the service restarts. |
| Allow Parallel Sessions | Lets a new run start while an earlier run's session is still active. Off: the new run is rejected. |
| Session Owner | The user who owns created sessions and receives their session notifications. |
| Workflow Parameters | Initial values supplied to the selected workflow. |
| Session Mode Toggles | Code review and verification for Develop sessions. |
| Tools & Capabilities | Tool, skill, MCP server, and Polygent MCP tool allowlists for the automation's sessions. |
A scheduled occurrence claimed before an unexpected service stop is recovered on startup. Polygent applies the saved missed-run option once: enabled occurrences run, disabled occurrences are skipped, and skipped one-time automations remain disabled.
Run Now
Run Now starts a session immediately and can override the starting branches for that run. It is not a dry run:
- On a One-time automation, Run Now consumes the occurrence and disables the automation.
- On a Recurring automation, the next run is recalculated from the current time, which shifts
@everyinterval schedules.
HTTP triggers
An HTTP trigger provides a webhook URL and a secret token so CI pipelines or external systems can start a run.
- Create an HTTP Trigger automation and save it.
- Copy the token and request examples shown in the automation editor. The token is displayed only then.
- Store the token in the caller's secret store.
- Call the webhook using the header form so the token is not written to URL logs or browser history.
| Request form | Call |
|---|---|
| POST (preferred) | POST {ClientUrl}/api/automations/http-trigger with header Api-Authentication: <token> and an optional JSON object body. |
| GET | GET {ClientUrl}/api/automations/http-trigger/<token>; query-string values become parameters. The header is also accepted and wins. |
curl -X POST "https://polygent.example.com/api/automations/http-trigger" \
-H "Api-Authentication: $POLYGENT_TRIGGER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"branch": "release/2.4", "reason": "nightly"}'
Request values become parameters: they fill {{name}} placeholders in an inline prompt and override stored workflow parameters with the same name. On POST, body values override query-string values with the same name.
| Limit | Value |
|---|---|
| Request body | 64 KB |
| Parameters per request | 100 |
| Size of one value | 8 KB |
| Response | Meaning |
|---|---|
200 | Run started. The body includes the session ID and URL, the execution ID, the automation name, and any unresolved placeholders. |
400 | Malformed JSON or invalid parameters. |
401 | No token was supplied. |
404 | The token is unknown, was regenerated, or the automation is disabled. |
409 | A previous run is still active and Allow Parallel Sessions is off. The body identifies the blocking execution and session. |
413 | The request body exceeds 64 KB. |
Regenerating the token invalidates the previous token immediately. Rotate it after suspected disclosure and update every caller. Disabling the automation makes every call return 404 without starting a session; the token is preserved, so re-enabling restores the original URL. HTTP-triggered automations do not use schedules or missed-run recovery. Possession of the token is permission to start the configured work.
Execution history
Execution history is the operator record for each attempted run.
History lists each run's start time, duration, trigger (Scheduled, Manual, Loop, or Webhook for HTTP calls), status, and linked session. Hover a Failed or Waiting to Resume status to read the error. Open the linked session for agent output, hook failures, verification results, and pending approval.
| Status | Meaning |
|---|---|
| Pending | Claimed and about to start. |
| Running | Session is active. |
| Approval | Waiting for a human approval. |
| Waiting for PR | Waiting for the run's pull request to be merged or closed. |
| Resolve Conflicts | Waiting for merge-conflict resolution. |
| Waiting to Resume | Interrupted; will resume when possible. |
| Completed | Finished successfully. |
| Failed | Finished with an error. |
Failure handling
Automatic disabling prevents a repeatedly failing automation from consuming capacity indefinitely.
- 3 consecutive failed sessions disable Recurring, Loop, One-time, and HTTP Trigger automations.
- A run that fails before its session starts counts toward the same limit for Recurring and Loop automations; a One-time automation whose run fails to start is disabled immediately.
- Manual automations are never disabled automatically.
- Deleting or disabling the automation's bot, or deleting its workflow, disables the automation immediately.
- When an automation is disabled automatically, its creator receives an inbox notification linking to the execution history.
After correction, run it with Run Now, verify success in execution history, then re-enable it.
Permissions
Permissions separate viewing from configuration and execution.
| Permission | Capability |
|---|---|
| View Own Automations | View the user's own automations and history. |
| View All Automations | View every automation and its history. |
| Manage Automations | Create automations; edit, enable, disable, delete, and run the user's own. |
| Manage All Automations | Edit, enable, disable, delete, and run any automation. |
Run Now requires a manage permission; there is no separate execute permission. HTTP callers authenticate with the automation token, not a user account.
Troubleshooting
These checks cover common automation incidents.
| Symptom | Check |
|---|---|
| Scheduled run did not start | Confirm the automation is enabled, the timezone and next run are correct, and a session host has capacity. |
| Missed run was not recovered | Confirm Auto Execute Missed Run is enabled and review execution history for an existing run. |
| Automation disabled itself | Read the inbox notification and the last failed run; check whether its bot or workflow was removed or disabled. |
| Loop stopped | A canceled loop session disables the loop. Correct the failure, test with Run Now, then re-enable. |
| Develop loop is idle | The previous run's pull request is still open; merge or close it. |
| Workflow parameters are missing | Match request or stored parameter names to the workflow's initial aliases. |
| HTTP trigger returns 401 | The caller sent no token; add the Api-Authentication header. |
| HTTP trigger returns 404 | The token was regenerated or the automation is disabled; update the caller or re-enable the automation. |
| HTTP trigger returns 409 | Wait for or complete the active session, or enable Allow Parallel Sessions. |
| Session remains open | Check approval state, file changes, and Complete only if no file changes. |