Move tasks and job templates between environments

Envoy bundles move task definitions and job templates between control planes without moving connector credentials, jobs, runs, or customer data. A bundle is newline-delimited JSON (NDJSON) so large exports and import results can stream.

Use bundles for promotion from development to production, controlled handoff between deployments, and backup of authored definitions. Use normal state backups for disaster recovery.

What a bundle contains

A bundle can include:

• current task YAML and task metadata;
• connector slot names and types, but no connector configurations;
• optional task version history;
• job template YAML;
• a manifest describing the export and filters.

Tasks appear before job templates so an import can validate template task references. Dashboard instances, instantiated jobs, connector bindings, runtime configuration values, secrets, and run history are not included.

Export from the UI

On Tasks, select one or more rows and choose Export. You can select the visible page or escalate to all tasks matching the current filters. A row's overflow menu also exports one task.

The UI exports current task versions. Use the API when you also need job templates or complete task version history.

Export through the API

Create an API key as described in Using the API, then request a bundle:

curl --fail-with-body \
  -H "Authorization: Bearer $ENVOY_API_KEY" \
  "https://envoy.example.com/api/export?include_tasks=true&include_job_templates=true&include_versions=true" \
  --output envoy-bundle.ndjson

Useful filters include task_name, job_template_name, include_archived, and status. Repeat the singular name parameters when exporting several exact names:

/api/export?task_name=pull-tickets&task_name=push-tickets

Treat bundles as configuration artifacts. Review and protect them even though they do not contain connector secrets; YAML can still reveal resource names, business rules, and data shapes.

Always preview an import

From Tasks, choose Import, select the .ndjson file, choose policies, and run Preview import. The preview performs server-side parsing and validation without writing rows.

Review every error before confirming. The summary distinguishes:

• create — a new task or template;
• update — changed content, status, or imported history;
• unchanged — equivalent YAML and status already exist;
• skip — excluded by policy;
• error — invalid or unavailable on the target.

An import rejects task YAML that fails validation, unavailable connector types, inconsistent version history, invalid DAGs, and job templates that reference missing tasks.

Choose an import mode

For name collisions, choose skip, overwrite, or error. overwrite creates a new task version when task content differs; it does not rewrite an existing version.

Archived task policy is separate:

• skip ignores archived tasks in the bundle;
• restore imports them as active;
• keep_archived preserves archived status.

Leave name normalization off unless you have deliberately reviewed a mismatch between the bundle name and YAML name.

API preview and import

Preview first:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $ENVOY_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @envoy-bundle.ndjson \
  "https://envoy.example.com/api/import?mode=upsert_current&conflict_policy=overwrite&dry_run=true"

The response is NDJSON: one result line per emitted item and a final summary line. If the preview has no errors, repeat with dry_run=false.

Promotion checklist

1. Export only the intended tasks and templates.
2. Store the bundle in an approved location.
3. Confirm the target has every required connector type.
4. Run a dry-run import and save its summary.
5. Import definitions.
6. Create or update target connector records separately.
7. Instantiate a fresh job and bind target connectors.
8. Run a bounded test and verify idempotency before scheduling.

Importing a definition does not prove that target credentials, network paths, upstream schemas, or destination permissions are compatible.