Auto-Sync Trigger Settings from integration.yaml

HeadlessOps automatically synchronises your trigger configuration from integration.yaml on every push. Changes to trigger type, cron schedule, or webhook method take effect immediately — no separate API call is needed to register them.

What Gets Auto-Synced

Every push, the platform reads the trigger block from your integration.yaml and persists the following fields:

All three are read and applied atomically on push — no extra step required.

How It Works

When the platform receives a push:

1. It reads integration.yaml from the incoming file tree.
2. It parses the trigger block and extracts type, cron, and method.
3. If any field changed since the last push, the platform:
   • Updates triggerType, cronExpression, and/or webhookMethod in the integration record.
   • For schedule triggers: cancels the existing cron job and registers a new one with the updated expression.
   • For webhook triggers: applies the new method filter immediately.
4. The push response includes the resolved trigger configuration.

This sync is reliable and consistent — the YAML is the single source of truth for trigger settings.

Two-Step vs. Single-Step Configuration

Previous approach (two operations required)

Previously, updating trigger settings required two separate operations — pushing the code, then calling the REST API to register the change:

# Push the updated YAML
git push

# Manually register the trigger change (required, or it would be ignored)
curl -X PUT https://app.headlessops.ai/api/integrations/my-integration \
  -H "Authorization: Bearer iter_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"triggerType": "schedule", "cronExpression": "0 * * * *"}'

Omitting the second step meant the new schedule was never activated, leading to silent misconfiguration.

Current approach (push is all you need)

Now the YAML and the platform stay in sync automatically:

# Push your updated integration.yaml — trigger settings apply immediately
git push

The push handler reads your YAML and applies any trigger changes as part of the same transaction.

Examples

Switching from Manual to Schedule

# Update integration.yaml to switch trigger type
trigger:
  type: schedule
  cron: "0 9 * * 1-5"  # Weekdays at 9am UTC

Push this file and the cron job is registered automatically. No additional API call needed.

Changing the Cron Expression

# Change an existing schedule
trigger:
  type: schedule
  cron: "0 9 * * 1"  # Every Monday at 9am UTC (was: daily at midnight)

The old cron job is cancelled and the new schedule is registered on push receipt.

Restricting Webhook Method

# Restrict an open webhook to POST only
trigger:
  type: webhook
  method: POST  # Was: ANY

The method filter is updated immediately — only POST requests trigger runs after the push.

What Is Not Auto-Synced

The following settings are not read from integration.yaml and must be set via the REST API or MCP:

• webhookAuthHeader / webhookAuthCredentialName — webhook authentication is kept out of the YAML for security reasons
• alertEmailUsers / alertWebhookUrl — failure notification recipients
• description metadata overrides and other non-trigger fields

Updating Existing Automation

If you have CI pipelines or scripts that call PUT /api/integrations/:name after every push specifically to update trigger fields, those calls are now redundant. The push handler applies trigger changes automatically — you can safely remove the extra API call.

Troubleshooting

Related

• Trigger Types — full reference for webhook, schedule, and manual triggers
• integration.yaml Schema — complete manifest schema reference
• push-run: On-Demand Runs — upload code and trigger a run in a single request