Triggering a change from an event
A trigger watches the events raised on a project, environment or asset, and acts when one matches. For example, when the upstream action succeeds on one asset, a trigger can run the downstream action on another. A trigger can:
- run a change
- start a workflow run
- call a webhook, sending it the event's source as JSON (through the API only)
Each trigger has two halves:
- When - the event to match: its type (such as
api:changes:success) and, optionally, attributes of the event's source (such as the change'saction). - Then - what to do, through a notification channel: the channel decides the kind of work (run a change, start a workflow run, call a webhook), and the trigger supplies the details, such as the target and action of the change.
Before you start
- A manual change must already succeed on the target. Run the target action by hand first. Otherwise the trigger fires but the change it starts fails, which is harder to diagnose.
- A webhook trigger needs a webhook channel, and is created through the API. A webhook channel holds the webhook's URL and credentials and is set up by an administrator. Triggers choose an existing webhook channel and never hold credentials themselves. A trigger that runs a change or starts a workflow run needs no channel set up beforehand.
- The trigger's creator needs the rights to do the work. A trigger always runs as the user who created it. For a trigger that runs a change or starts a workflow run, that user needs
executeon its target, the same right as running it by hand, and does not needupdateon the node. For a webhook trigger, that user needsupdateon the node,executeon the webhook channel andupdateon the channel'sevent_subscriberspath. See who can do what.
Create a trigger in the GUI
-
Open the project, environment or asset whose events you want to act on, and select the Triggers tab.
-
Click Create trigger.
-
Under Name, enter the trigger's Name and Code. Both are required, and the code can use only lowercase letters, digits and underscores. The code must be unique across MintPress, so include something specific to the node, such as its code. It cannot be changed later. Turn off Enabled to create the trigger paused.
-
Under When, choose the Event type and, optionally, conditions on the event source. The trigger matches events on this node and the nodes below it. Beside the form, Would have matched lists recent events on this node and below and whether each would match, naming the first rule a missed event fails. It lists only events you can read.
-
Under Then, choose What to do:
- Run a change - choose the target node and the action. For a project or environment target, also choose the Git remote and revision. An asset target runs a templated change and needs neither.
- Run a workflow - choose the workflow and its version.
The trigger uses the channel MintPress provides for that kind of work, so there is no channel to set up.
-
Click Create trigger. An enabled trigger starts matching events straight away.
The Triggers tab lists the node's triggers. Use Disable to pause one without losing it, and Delete to remove it.
A trigger the editor cannot show exactly opens read-only, with a note to change it through the API. Examples are a trigger that calls a webhook, and a trigger created through the API with an event type rule that matches a pattern rather than one exact type, or with a target taken from the event. A trigger created by someone else also opens read-only, unless you are a superuser, and so does a trigger inherited from a node above, which you change on that node. When one of these also uses settings the editor cannot show, its note warns that the form may not match what the trigger does. All of them can still be enabled, disabled and deleted.
Create a trigger with the API
Send POST to the node's triggers path with Content-Type: application/vnd.api+json. This request creates a trigger on the source_app asset that runs downstream on target_app whenever an upstream change on source_app succeeds:
POST /api/projects/evt_demo/environments/dev/assets/source_app/triggers
{
"data": {
"attributes": {
"code": "downstream_on_upstream_success",
"description": "Run downstream on target_app when upstream succeeds",
"rules": {
"event_rules": [
{ "attribute": "type", "predicate": "eq", "value": "api:changes:success" }
],
"source_rules": [
{ "attribute": "action", "predicate": "eq", "value": "upstream" }
]
},
"create_channel_for_job": "create_change_job",
"channel_kwargs": {
"parent_path": "/projects/evt_demo/environments/dev/assets/target_app",
"action": "downstream"
},
"enabled": true
}
}
}
codeis required and identifies the trigger. It must be unique across MintPress, so include something specific to the node, such as its code. It can use only lowercase letters, digits and underscores, and cannot be changed later.descriptionis the name the GUI shows.rulestakes the sameevent_rulesandsource_rulesas an event filter. Leave out any rule onevent_node_pathorsystem: MintPress adds both. Thesystemrule matches only events MintPress raises when the trigger's event types are ones MintPress raises, and only events users create when they are custom event types. A trigger that mixes the two kinds is refused withcannot mix event types OpsChain raises with custom event types, as is one whose ownsystemrule disagrees with its event types.create_channel_for_jobis set tocreate_change_joborcreate_workflow_run_jobfor a trigger that runs a change or starts a workflow run. MintPress then uses the channel it provides for that job, which has nokwargsof its own and cannot be changed or deleted.- Instead,
channel_parent_pathandchannel_codename an existing channel, and are required for a webhook trigger. A channel's parent path is the path of the node it was created on, whether a project, environment or asset. Leavechannel_parent_pathout for a channel created in the system configuration. channel_kwargsholds the trigger's own details:
| Then | Channel's job | channel_kwargs |
|---|---|---|
| Run a change | create_change_job | parent_path and action; for a project or environment target, also git_remote_name and git_rev |
| Start a workflow run | create_workflow_run_job | project_code, code (the workflow) and version |
| Call a webhook | send_to_webhook | Optionally serializer_params; url only when the channel does not set one |
The response is the trigger, and accepts include=event_filter,notification_channel. Use GET on the same path to list the node's triggers and those of the nodes above it, which fire for this node too, and PATCH or DELETE on <node path>/triggers/<id> to change or remove one of the node's own triggers.
A value the channel sets in its own kwargs overrides the same key in every trigger that uses it, so a shared channel must leave the target empty. MintPress refuses to create a trigger whose details the channel would override.
Use values from the event
channel_kwargs values can use Mustache placeholders, filled in from the matched event when the trigger fires: {{event.<attribute>}} for the event's own attributes, and {{source.<attribute>}} for its source's. For example, to run the action on the asset that raised the event:
"channel_kwargs": {
"parent_path": "{{event.event_node_path}}",
"action": "downstream"
}
A placeholder that names an attribute the event or its source does not have stops the trigger, and raises an api:event_processor:error event.
Which events a trigger matches
A trigger matches events raised on its own node and on every node below it. A trigger on a project therefore also fires for events on its environments and assets, while a trigger on an asset fires only for that asset's events. Events on a node with a similar code, such as project bank2 for a trigger on project bank, never match.
The Triggers tab also shows triggers created on the nodes above, when you can read those nodes, because they fire for this node too. They are read-only there and name the node they belong to. Open that node to change them.
A trigger on an event type MintPress raises, such as api:changes:success, never fires for an event a user creates with the same type through api/events. A trigger on a custom event type fires only for events users create. MintPress treats any type starting with api:, audit:, error:, info:, opschain:, warn: or warning: as one it raises, so give custom event types a different prefix, such as myapp:deployed. A trigger on info:myapp:deployed never fires for an event a user creates.
Each event starts a given target and action at most once, so an event that is raised again does not start a duplicate change.
A change or workflow run started by a trigger raises events of its own, which can match other triggers. MintPress stops such chains, as described in notification loops.
Who can do what
A trigger always runs as the user who created it, whoever enabled or last changed it. Its change or workflow run is started with that user's rights, and appears as theirs.
| Task | Who can do it |
|---|---|
| See a trigger | Anyone with read on its node |
| Create a trigger that runs a change or starts a workflow run | Anyone with execute on the change's target or on the workflow |
| Create a trigger that calls a webhook | Anyone with update on its node, execute on the webhook channel and update on the channel's event_subscribers path |
| Enable or disable a trigger | Its creator, or anyone with update on its node |
| Delete a trigger | Its creator, or anyone with delete on its node |
Change what a trigger does - its event rules, channel or channel_kwargs | Its creator, or a superuser |
A trigger that runs a change or starts a workflow run is checked against its creator's execute on its target, the right it uses each time it fires. Creating one, or changing its target, is refused unless the creator has execute there, and so is enabling a disabled one once the creator has lost it. A target taken from the event with Mustache ({{ }}), which is possible only through the API, cannot be checked in advance, so it is checked only when the trigger fires.
Disabling or deleting a trigger only stops it running, so its creator can always do both, even without update or delete on the node. In the GUI, a trigger created by someone else opens read-only with its creator shown, unless you are a superuser, and only Enable, Disable and Delete are available, to users with update or delete on the node.
A trigger that calls a webhook sends data outside MintPress, so it needs execute on the webhook channel's path, as described in resource paths. That check is always made against the creator's rights, never the rights of the user making the request:
- Creating a webhook trigger, or changing its channel or URL, is refused unless the creator has
executeon the channel. - Enabling a disabled webhook trigger is refused once the creator has lost
executeon the channel, or the right to subscribe to it, even when the user enabling it has both. - The webhook receives only what the creator can read. For example, a node's properties are left out of the payload when the creator cannot read them.
Disabling and deleting a trigger are never refused on these grounds, since they only stop it running.
Check that a trigger works
Open the trigger from the Triggers tab and read its History. Each time the trigger fired, it lists when (Fired), the Matched event, the Outcome, the change or workflow run it Started and that activity's Status.
You can also run the source action, then look for a new change on the target. Its metadata names the event and the trigger that started it:
{
"opschain": {
"activity_depth": 1,
"source_event_id": "<id of the matched event>",
"source_event_subscriber_id": "<id of the trigger>"
}
}
Inside the target action, the same id is available as OpsChain.context.change.metadata.dig(:opschain, :source_event_id).
| Symptom | Cause and fix |
|---|---|
| No change on the target, and no error event | The trigger did not match. Compare the event's type, the node it was raised on and its source's attributes with the trigger's rules. Check that the trigger and its channel are both enabled. |
An api:event_processor:error event | The trigger matched, but the work could not be started. The event's message gives the reason, such as a bad parent_path, a missing action, or a creator without execute on the target. |
| A project or environment target fails | Only asset targets run as templated changes. Other targets need git_remote_name and git_rev in the trigger's channel_kwargs. |