Skip to main content
In addition to configuring triggers via UI, you can also configure triggers in code. You can either manually define the triggers in code or you can go to the triggers detail page in the UI and click the button labeled Save trigger in code on the left side panel to store the current trigger’s settings to code.

​
How triggers in code are synced to the database and UI

  • Source of truth: The triggers.yaml file is the source of truth for trigger definitions.
  • Sync flow: A background scheduler process periodically syncs triggers from triggers.yaml into the database. Only triggers that pass the envs filter (see Envs filter) are created or updated on that instance. After a trigger is synced to the database, it appears in the Triggers UI.
  • New/updates flow both ways: New or updated triggers in the YAML are pushed to the database when the scheduler runs. Edits you make in the UI to a trigger that’s defined in code are written back to triggers.yaml so UI and code stay in sync.
  • Deletions are not synced: Removing a trigger from triggers.yaml does not remove it from the database. You must delete the trigger in the UI (or via API) to remove it from the database. See Delete triggers.

​
Create and configure triggers

Here are the steps to create and configure triggers via code:
  1. Create a triggers.yaml file under your pipeline folder. The file path should be pipelines/[pipeline_uuid]/triggers.yaml.
  2. Enter your trigger configs into the triggers.yaml file.
    1. Content structure
    2. Required trigger fields
      • name: Unique identifier of the trigger (per pipeline).
      • schedule_type: time or api for new triggers. event is deprecated and should only be used to maintain existing legacy event triggers.
      • For time (schedule) triggers: schedule_interval and start_time are required.
        • schedule_interval: @once, @hourly, @daily, @weekly, @monthly, @always_on, or a Cron expression (e.g. * * * * *).
        • start_time: Persisted schedule start timestamp. For @once, this is the single run time (e.g. 2023-01-01 or 2023-01-01 00:00:00).
      • For api triggers: schedule_interval and start_time are typically not used for execution but may still be present in the config.
    3. Optional trigger fields
      • status: active or inactive. Defaults to inactive if omitted.
      • variables: A dictionary of runtime variables for this trigger.
      • sla: SLA in seconds for this trigger.
      • settings: A dictionary of advanced settings:
        • skip_if_previous_running: true/false — do not start a new run if the previous run is still in progress.
        • allow_blocks_to_fail: true/false — allow the pipeline to continue running non-dependent blocks if some blocks fail.
        • create_initial_pipeline_run: true/false — create an initial run when the start time is in the past (schedule triggers).
      • envs: List of environments where this trigger should be synced and run. See Envs filter below.
  3. Save the triggers.yaml file. On the next scheduler run, trigger configs are synced to the database (subject to the envs filter) and then show in the Triggers UI.
    1. Required trigger fields
      1. name: Unique identifier of the trigger
      2. schedule_type: time or api for new triggers. event is deprecated for legacy event triggers only.
      3. schedule_interval: @once, @hourly, @daily, @weekly, @monthly, @always_on, or Cron syntax(* * * * *)
      4. start_time: Persisted schedule start timestamp. For @once, this is the single run time (e.g. 2023-01-01)
    2. Optional trigger fields
      1. status: active or inactive
      2. variables: A dictionary of variables that’s associated with the trigger
      3. sla: SLA in seconds
      4. settings: a dictionary of advanced settings
        1. skip_if_previous_running: true/false
        2. allow_blocks_to_fail: true/false
        3. create_initial_pipeline_run: true/false
      5. envs: The environments that the trigger runs in.
        • If envs is not set or empty, the trigger will run in all environments.
        • The environment of the Mage app is set via the ENV environment variable.
        • OSS: Only supports dev, staging, prod, test.
        • Mage Pro: Supports any value, which must match the ENV environment variable.
  4. Save the triggers.yaml file. The trigger configs will be synced to the triggers UI shortly.

​
Example triggers config:

​
Envs filter

The optional envs field limits which instances or workspaces sync and run the trigger. Each instance/workspace has an environment set by the ENV environment variable.
  • When envs is not set or empty: The trigger is synced to all instances/workspaces. Every environment will get the trigger in the database and can run it.
  • When envs is set: The trigger is synced only to instances/workspaces whose ENV value is in the envs list. Other instances will not create or update this trigger in their database, so they will not run it.
    • OSS: Allowed values are dev, staging, prod, and test.
    • Mage Pro: Any value is allowed; it must match the ENV set for that instance or workspace.
If you add an envs filter to a trigger that already exists everywhere: Triggers that were previously synced (e.g. when envs was empty) remain in the database on instances that no longer match the new envs list. The sync process only creates or updates triggers; it does not delete them. To stop such a trigger from existing (and running) on those instances, you must delete the trigger manually in the UI on each affected instance or workspace.

​
Modify triggers

If an existing trigger is defined in the YAML file, changes flow both ways: updates in the UI are written back to triggers.yaml, and updates in the YAML are synced to the database (and reflected in the UI when you reload). Only triggers that pass the envs filter are synced to the database on each instance.

​
Delete triggers

The triggers.yaml file is synced into the database automatically, but deletions work differently:
  • Delete one trigger: Removing a trigger from the YAML file does not delete it from the database. Delete it in the UI on each instance where it exists:
    • In the Pipeline triggers table (/pipelines/[pipeline_uuid]/triggers), click the trash can icon.
    • In Mage Pro, right-click the trigger row and click Delete.
  • Delete selected triggers in Mage Pro: On the global Triggers page, select one or more rows on the current page, open Actions, and choose Delete selected (N). Selection applies only to the visible page and does not carry across pagination.
  • Delete matching triggers in Mage Pro: Apply at least one search term or filter on the global Triggers page, then open Actions and choose Delete matching triggers. This action is unavailable without a search term or filter. Mage previews the matching count across all pages and requires you to type DELETE exactly before deletion. If the set of matching triggers changes after the preview, Mage stops the deletion so you can review the filters again. Triggers outside the current search and filters are not deleted.
The Mage Pro bulk deletion actions require Editor access. Each request can delete up to 100 triggers and cancel up to 100 associated active runs; refine the selection or filters, or wait for active runs to finish, if either limit is exceeded. It removes each trigger’s database record and its definition from the pipeline’s triggers.yaml file. Mage marks observed initial and running pipeline-run and block-run records as cancelled and attempts to stop their executors. Executor cancellation is best effort, so a worker or a run created concurrently by another scheduler process may continue after the trigger is deleted. Run and block-run history is preserved, and completed, failed, and already-cancelled runs are unchanged. After Mage commits the trigger’s inactive state, a cancellation or final deletion failure leaves the trigger and its YAML definition inactive so you can retry. If an envs filter previously created the trigger on other instances, delete it manually on those instances as well; sync does not remove triggers from their databases. As a reversible alternative, set the trigger’s status to inactive in triggers.yaml. Status changes are automatically synced to the database and UI.