Scheduling & Triggers

VersionForge supports three ways to start a sync: manual trigger, cron-based scheduling, and API calls. You can combine these approaches -- for example, run a scheduled daily sync and allow manual triggers for ad-hoc refreshes.

Manual Trigger

The simplest way to start a sync is from the dashboard.

1. Open the pipeline

   Navigate to Pipelines and select the pipeline you want to run.

2. Click Run Sync

   Click the Run Sync button in the top-right corner of the pipeline detail page.

3. Monitor progress

   The pipeline log updates in real time, showing the current stage (Extract, Stage, Diff, Transform, Review, Load) and row counts at each step.

Manual triggers are useful for testing new configurations, running one-off refreshes after source system changes, and debugging pipeline issues.

Cron-Based Scheduling

For recurring syncs, you can configure a cron schedule on any pipeline.

Navigate to Pipeline Settings > Schedule and enter a cron expression:

| Expression | Schedule | |---|---| | 0 6 * * 1-5 | Every weekday at 6:00 AM UTC | | 0 */4 * * * | Every 4 hours | | 0 8 1 * * | First day of every month at 8:00 AM UTC | | 30 22 * * 0 | Every Sunday at 10:30 PM UTC |

Schedule Best Practices

• Align with source system refresh cycles -- If your ERP runs a close process at 5:00 AM, schedule the sync for 6:00 AM to capture fresh data.
• Stagger pipelines -- If you have multiple pipelines hitting the same source, offset their schedules by 15-30 minutes to avoid rate limit contention.
• Avoid peak hours -- Schedule large syncs (50,000+ rows) during off-peak hours for your target system.

API-Triggered Syncs

You can trigger a sync programmatically by calling the VersionForge API. This is ideal for integrating syncs into CI/CD pipelines, responding to webhooks from source systems, or building custom orchestration.

curl -X POST https://app.versionforge.com/api/v1/sync/trigger \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pipeline_id": "pipe_abc123" }'

The response includes a run_id you can use to poll for status:

{
  "run_id": "run_7f3a2b",
  "status": "started",
  "pipeline_id": "pipe_abc123",
  "triggered_by": "api",
  "started_at": "2026-04-12T14:30:00Z"
}

To check the status of a running sync:

curl https://app.versionforge.com/api/v1/sync/runs/run_7f3a2b \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Trigger.dev Integration

VersionForge uses Trigger.dev for background job processing. This provides:

• Durable execution -- Long-running syncs survive server restarts and transient failures
• Automatic retries -- Failed stages are retried with exponential backoff (configurable per pipeline)
• Observability -- Every job is tracked with detailed logs, duration, and retry history

You do not need to configure Trigger.dev directly. It runs behind the scenes when you use any of the three trigger methods.

Retry Behavior

When a sync stage fails (e.g., a source system timeout during extraction), VersionForge retries automatically:

| Attempt | Delay | Behavior | |---|---|---| | 1st retry | 30 seconds | Retry the failed stage only | | 2nd retry | 2 minutes | Retry the failed stage only | | 3rd retry | 10 minutes | Retry the failed stage only | | After 3 failures | -- | Pipeline marked as failed, notification sent |

You can customize retry limits and delays in Pipeline Settings > Retry Policy. You can also disable retries entirely for pipelines where you prefer to investigate failures immediately.

Monitoring Scheduled Runs

The Runs tab on each pipeline shows a complete history of all sync runs, including:

• Trigger type (manual, scheduled, API)
• Start time and duration
• Row counts (extracted, diffed, approved, loaded)
• Status (running, completed, failed, cancelled)

You can filter runs by status and date range, and export the run history to CSV.