Promotions

Promotion moves reviewed definitions between Sets while preserving dependencies and destination-specific changes. Preview is the default.

Preview and apply#

Preview what would change without writing any files:

$ npx eventvisor promote --from=development --to=staging

Apply the reviewed plan explicitly:

$ npx eventvisor promote --from=development --to=staging --apply

Promotion never writes by default. Applied changes remain ordinary Git changes that can be reviewed and committed.

Restrict allowed flows#

Configure allowed paths in eventvisor.config.js:

module.exports = {
  sets: true,
  promotionFlows: [
    { from: "development", to: "staging" },
    { from: "staging", to: "production" },
  ],
};

When promotionFlows is present, an unlisted direction fails instead of guessing what the release process allows.

Filtering#

Without filters, promotion selects every authored entity from the source Set. Narrow the plan with repeatable Targets, tags, or event patterns:

$ npx eventvisor promote --from=development --to=staging --target=checkout
$ npx eventvisor promote --from=development --to=staging --target=web --target=backend
$ npx eventvisor promote --from=development --to=staging --tag=payments
$ npx eventvisor promote --from=development --to=staging --include-events='checkout.*' --exclude-events='checkout.internal.*'

Selected definitions bring their transitive runtime dependencies. Effects triggered by selected events or attributes are included, along with tests that cover the selected contract. Target patterns use the same glob-like * matching as Target entity filters.

An empty filtered plan fails by default. Use --allow-empty only when an empty result is intentional in automation.

What promotion moves#

Promotion can move events, attributes, destinations, effects, reusable Schemas, Targets, and tests. It merges selected source definitions into the destination Set. Destination-only definitions remain untouched, and promotion does not interpret absence from the source as a deletion.

Protected definitions#

Set promotable: false on an entity when an existing destination definition must remain specific to that Set:

description: Production warehouse
promotable: false
transport: http

An existing entity is protected when either the source or destination marks it as non-promotable. A missing destination entity is still created so a new Set can receive a complete dependency graph.

Conflict handling#

The default source policy lets source values win where both definitions contain different values. Destination-only fields remain in the merged result.

$ npx eventvisor promote --from=development --to=staging --conflicts=source --apply
$ npx eventvisor promote --from=development --to=staging --conflicts=destination --apply
$ npx eventvisor promote --from=development --to=staging --conflicts=fail

Use destination to preserve conflicting destination values. Use fail when any conflict should stop the operation, which is useful in strict release automation.

Validation and rollback#

After writing an applied promotion, Eventvisor lints the destination Set. If linting fails, every file changed by that promotion is restored or removed as appropriate.

Audit output#

Add --audit to write a machine-readable JSON record below .eventvisor/promotions/:

$ npx eventvisor promote --from=development --to=staging --apply --audit

The record contains the source and destination Sets, whether changes were applied, selected entities, and conflict paths.

Recommended workflow#

1. Preview the promotion.
2. Review the selected entities and conflicts.
3. Apply with --audit when a durable operation record is useful.
4. Run tests and build the destination Set.
5. Review the resulting Git changes in a pull request.

$ npx eventvisor test --set=staging
$ npx eventvisor build --set=staging

Related#

• Sets
• Environments
• Targets