Skip to main content

# Automations

Automations run tasks or deployment profiles from a schedule, a manual run, an inbound webhook, or SCM polling. Each automation belongs to a single environment and creates normal CoderFlow tasks when it runs.

## Where to Manage​

1. Open Administration -> Environments.
2. Select an environment.
3. Open the Automations tab.

From this tab you can create, edit, enable/disable, run now, view history, and delete automations.

## Creating an Automation​

Click Add Automation and configure:

- Name and optional Description
- Schedule using the picker:
  - None (webhook only)
  - Daily
  - Weekly
  - Monthly (one or more days, 1-28)
  - Recurring (interval + optional time window + optional days)
  - Custom cron expression
- Run Target:
  - Custom instructions for manual-style tasks
  - Task template (from environment templates) with parameter values
  - Deployment profile (from environment deployment profiles) with parameter values
- Agent for task-based automations:
  - Claude, Codex, Gemini, Bob, or Grok
  - Optional Claude effort level override
  - Optional Codex reasoning level override
  - Optional Grok effort level override
- Task Name Template (supports `{{date}}` and `{{datetime}}`) for task-based automations
- Enabled toggle

Save to activate the automation.

## Git Authentication for Scheduled Runs​

Scheduled automations run as a background system action, not as the interactive user who created them.

- Repository operations for scheduled automation tasks use the configured app/provider identity
- Provider audit logs will show the app/bot identity rather than an individual user
- If a repository or branch policy requires a real user identity, scheduled pushes may still be blocked by the provider

## Webhook Triggers​

Automations can also be triggered by inbound webhooks. Create a webhook from the Webhooks subtab, copy its inbound URL, and configure the external system to send a `POST` request to that URL.

The inbound URL has this shape:

    https://<server>/api/webhooks/inbound/<token>

Webhook tokens are secret. Rotate the token if it is exposed, and use signature verification when the sender supports it.

For signature schemes, payload variables, delivery history, GitHub and Stripe examples, webhook-only ingress, and SCM polling, see Webhooks & SCM Triggers.

### Optional Webhook-Only Ingress Listener​

By default, inbound webhook routes are served by the main CoderFlow server. Production deployments can instead start a second webhook-only HTTP listener and expose only that port publicly while keeping the main CoderFlow application port private.

This is route and port isolation, not process isolation. The listener runs inside the same Node process as the main CoderFlow server, so it reduces the public HTTP route surface but is not a separate process, user, container, or privilege boundary.

Set one of the following before starting the server:

    WEBHOOK_INGRESS_MODE=listener
    WEBHOOK_INGRESS_PORT=3003
    WEBHOOK_INGRESS_HOST=0.0.0.0

`WEBHOOK_INGRESS_PORT` by itself also enables listener mode. `WEBHOOK_INBOUND_PORT` and `WEBHOOK_INBOUND_HOST` are accepted aliases.

The webhook-only listener serves:

- `GET /health`
- `POST /api/webhooks/inbound/:token`

It does not serve the CoderFlow web UI, authenticated APIs, webhook management APIs, or static assets. When using a separate public hostname or port, configure the external provider with that listener's base URL plus the inbound token path.

## Schedule Notes​

The schedule picker stores a cron expression internally.

Examples:

- Daily at 2:00 AM -> `0 2 * * *`
- Weekly Monday 9:00 AM -> `0 9 * * 1`
- Monthly 1st at midnight -> `0 0 1 * *`
- Monthly 1st and 16th at midnight -> `0 0 1,16 * *`
- Every 30 minutes -> `*/30 * * * *`
- Every 30 minutes, 9 AM-5 PM, weekdays -> `*/30 9-17 * * 1,2,3,4,5`

## Managing Existing Automations​

Each row in the Automations table provides:

- On/Off toggle to enable or disable scheduling
- Run Now to trigger immediately
- History to view recent runs and linked tasks
- Edit to update configuration
- Delete to remove the automation

## Run History​

History shows:

- Trigger time
- Trigger source (`manual`, `schedule`, `webhook`, or `scm-poll`)
- Run status
- Link to the generated task or deployment result

For SCM polling runs, history also shows the old and new commit SHA, commit message, and commit link when the provider supplies them.

Task-based automations can open the main task list filtered by automation. Deployment automations link to the environment's deployment history for the selected profile.

## Task List Integration​

Automation-created tasks can be filtered from the main task board with:

- `index.html?automation=<automationId>`

When this filter is active, the task board shows a filter banner. Automation tasks also show an automation badge on task tiles linking back to the automation history view.