Triggering Astra

Astra runs one job at a time per site, and every job has a trigger — the signal that caused it to start. There are two kinds: manual and automatic.

This page covers both, plus Watch Mode for deploy-time scrutiny.

Manual Triggers

Manual triggers are the simplest way to use Astra. You spot something in the dashboard, click a button, and Astra starts a job. Manual triggers bypass the auto-trigger filters — they always run, as long as the site has an active add-on and credits available.

Manual trigger buttons live in these tabs:

Errors Tab

• Fix with Astra button on any error row → opens an error_fix job for that error group

Methods Tab

• Fix N+1 button next to methods flagged by the N+1 detector → opens an n1_optimization job
• Optimize button on slow methods → opens a general_optimization job with the method trace as context
• Migrate APIs button on methods using deprecated sync Meteor APIs → opens a deprecated_api_migration job

Database Tab

• Add Index button on queries flagged with COLLSCAN → opens an index_recommendation job
• Optimize Query button on slow aggregations → opens a query_optimization job

System Tab

Accessed via the sub-tabs of the System view:

• Code Health sub-tab:
  • Fix Pub button on over-fetching publications → publication_optimization
  • Migrate button on deprecated API usage → deprecated_api_migration
• Security sub-tab:
  • Patch Vuln button on npm audit findings → vulnerability_fix

Manual first, automatic later

We recommend using manual triggers only for at least the first week. This lets you see the kind of PRs Astra files for your codebase before putting it on autopilot.

Automatic Triggers

When Auto-Trigger is enabled in Configure → Trigger Settings, Astra watches the signals from the agent and fires jobs on its own when an issue matches the configured filters.

Automatic triggers are gated by:

1. Auto-Trigger enabled — the master on/off toggle
2. Min Severity — errors below this severity do not trigger
3. Min Error Count — the issue must occur at least this many times before triggering
4. Cooldown — the minimum gap between automatic triggers on the same site (default: 60 minutes)
5. Exclude Patterns — regex patterns; matching errors are skipped
6. Allowed Job Types — only types in this list are permitted to run automatically

A job that fails any gate is logged and suppressed — no credit is spent.

Recommended First Configuration

Auto-Trigger:       On
Min Severity:       High
Min Error Count:    5
Cooldown:           60 minutes
Exclude Patterns:   timeout|ECONNREFUSED|ECONNRESET
Allowed Job Types:  error_fix, vulnerability_fix, deprecated_api_migration

This configuration:

• Waits until an error has happened 5 times before firing (filters out flakes)
• Ignores transient network errors via the exclude regex
• Only runs the three safest job types automatically
• Respects a 1-hour cooldown so a traffic spike cannot trigger a job storm

Once this feels stable, add n1_optimization and index_recommendation to the allowed list.

Exclude Patterns

Exclude patterns are JavaScript regexes matched against the error message. You can add up to 20. Useful patterns:

Pattern	Excludes
timeout|ECONNREFUSED|ECONNRESET	Transient network errors from third-party APIs
Cannot read propert.* of undefined	Broad catch-all (use cautiously — hides real null-safety bugs)
^NotAuthenticatedError	Expected auth errors you surface in UX
Stripe.*rate_limit	Errors you already alert on via your Stripe integration

Watch Mode

Watch Mode is a time-boxed auto-trigger that runs only for a set duration after a deployment. It is designed for the highest-risk window — the minutes just after a release ships.

When Watch Mode is on:

1. SkySignal detects a new deployment (from the Deployments tab — either the GitHub webhook or the agent's appVersion change)
2. Astra arms itself for the configured window (default: 10 minutes)
3. Any error that appears during the window triggers a job immediately, without waiting for the Min Error Count threshold
4. After the window expires, Astra reverts to whatever Auto-Trigger config was set (including off)

Watch Mode respects the Min Severity, Exclude Patterns, and Allowed Job Types filters — only the error count threshold is waived.

When to use Watch Mode

Turn on Watch Mode for a site that ships multiple times a day to production. The 10-minute window after each deploy is when regression risk is highest; Watch Mode gets Astra diagnosing and filing a fix PR before your on-call rotation even sees the page.

Behavior Settings

In addition to triggers, three Behavior toggles in the Configure panel control what happens once a job is running:

Require Approval

When on, Astra runs the full pipeline (analyze → fetch → fix → test) but holds at awaiting_approval before creating the PR. You get a notification, review the proposed change inside the dashboard, and approve or cancel. Only approved jobs push to GitHub.

Use this on sites where you want Astra to analyze aggressively but only open PRs under supervision.

Run Tests

When on, Astra runs your configured test command in a sandbox before creating the PR. If tests fail, the PR is opened as draft with the test output included.

This is slower (typically +2-4 min per job) but dramatically improves PR quality.

Auto-Create Issues

When on, errors that Astra cannot fix automatically open a GitHub Issue in the target repo instead of failing silently. The issue includes the error, stack trace, and Astra's diagnostic notes — useful for triage even when a fix is out of scope.

Webhook Notifications

Configure a Webhook URL in the Behavior section to receive a POST when any Astra job completes. The payload matches the standard Slack / Discord incoming-webhook format and is handy for:

• Posting PR links to a #astra Slack channel
• Routing jobs into a PagerDuty or Linear workflow
• Logging every Astra action into an audit channel

Cost Control

Every automatic trigger spends credits. Three levers keep costs predictable:

• Cooldown — a 60-minute cooldown caps automatic jobs at 24/day per site
• Allowed Job Types — restrict to the cheapest types (error_fix is typically the lowest credit cost)
• Min Severity / Min Error Count — higher thresholds mean fewer triggers

The add-on status bar at the top of the AI DevOps tab shows live credit usage against your $50 monthly allowance. If you exhaust your allowance and overage is disabled, automatic triggers are suppressed until the next billing cycle.

Next Steps

• Job Types — What each of the eight job types produces
• Getting Started — Activate Astra on your first site
• Overview — How Astra's pipeline works end to end