# Events and triggers (https://www.shipfox.io/docs/understand/events-and-triggers)

Description: 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 [#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](https://www.shipfox.io/docs/integrations). For
built-in sources, see [Run manually](https://www.shipfox.io/docs/how-to/author-workflows/run-manually) and
[Schedule workflows](https://www.shipfox.io/docs/how-to/author-workflows/schedule-workflows).

## How a trigger decides to create a run [#how-a-trigger-decides-to-create-a-run]

A trigger asks three questions.

1. Did the event come from the named source?
2. Is it an event type that this workflow handles?
3. 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 [#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 [#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](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/event-routing) to tell a delivery problem
from a filter problem. The [Expressions
reference](https://www.shipfox.io/docs/reference/expressions) defines the expression syntax. The
[Contexts reference](https://www.shipfox.io/docs/reference/contexts#context-availability) defines the
available data.

## New work, retried work, or continued work [#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.