Events and triggers
Understand why Shipfox records events separately from the workflow triggers that decide whether an event creates a run.
An event is a record that something happened, such as a push or a new issue. A trigger is the rule in a workflow that decides whether an event creates a run.
Shipfox keeps them separate because one event can matter to several kinds of work. A push can start tests, a security review, and a deployment check. The Git provider doesn't need to know about any of them.
The provider reports what happened. The workflow decides what to do about it.
Where events come from
An integration connection receives events from one external account or installation. Each event records its source, its event name, a delivery identity, a time, and its data.
The source matters as much as the event name. Two GitHub integration connections can both send a push event, but they represent different accounts and different repositories. A trigger names the integration connection that it accepts events from.
Provider event names live in the Integrations reference. For built-in sources, see Run manually and Schedule workflows.
How a trigger decides to create a run
A trigger asks three questions.
- Did the event come from the named source?
- Is it an event type that this workflow handles?
- Does its data pass the optional filter?
When a trigger omits event, it accepts every event from that source.
Only a match creates a run. The event still exists when no trigger matches. A team can therefore inspect the delivery of an event separately from the workflow policy.
This split also means a team can change a workflow without reinstalling the integration. The integration connection continues to receive events. The workflow files in each repository decide what those events mean for that project.
One event can start several runs
Shipfox checks each delivered event against every trigger that listens for it. Each matching trigger creates its own run.
Several runs from one event are useful when the work has separate owners or separate failure rules. A test workflow and an incident workflow can react to the same event without sharing a job graph or a result. The cost is separate compute and separate history for each run.
Put related work in one workflow when it needs one shared result or one visible run. Use separate workflows when each response must stand alone.
How filters work
A trigger filter narrows events by data such as branch, project, or severity. Shipfox evaluates the filter before it creates a run. A false result creates no run.
An expression error also creates no run. Shipfox refuses to start work when it can't prove that the event passes the filter. This also means that a wrong field path looks like a missing run, not like a failed job.
Use the event journal and the event-routing guide to tell a delivery problem from a filter problem. The Expressions reference defines the expression syntax. The Contexts reference defines the available data.
New work, retried work, or continued work
Each mechanism creates a different kind of record.
| Mechanism | Use it when | What Shipfox creates |
|---|---|---|
| External event trigger | A delivered event starts independent work. | A new run. |
| Manual trigger | A person needs a new run on demand. | A new run. |
| Schedule | Time, not an external event, starts recurring work. | A new run for each tick. |
| Feedback loop | A check says the current work isn't ready. | A new step attempt in the same job execution. |
| Listening job | A later event continues work that the run already represents. | A new job execution in the same run. |
The question to ask isn't where the event came from. Ask whether it starts new work, revises failed work, or continues existing work.