1# CI events
2
3| Event | Workflow read from | Runs on | Trusted when the owner caused it and… |
4|---|---|---|---|
5| `push` | pushed commit | pushed ref | pushed it |
6| `pull_request` | test merge commit | `refs/pull/<n>/merge` | pushed both head and base |
7| `pull_request_target` | default branch | default branch tip | pushed the default branch tip |
8| `workflow_dispatch` | chosen ref | chosen ref | moved that ref to its commit |
9| `schedule` | default branch | default branch tip | last moved the default branch |
10| `workflow_run` | default branch | default branch tip | inherits the triggering run, never more |
11| `create` | created ref | created ref | pushed it |
12| `delete` | default branch | default branch tip | pushed the default branch tip |
13
14`ermite run list`, `run view` and the Actions pages show the event of each run.
15
16## `pull_request`
17
18A merge request is a pull request for workflows.
19
20- `refs/pull/<n>/head` follows the source branch. `refs/pull/<n>/merge` is a test merge with the target, while it merges cleanly. Both can be fetched, never pushed.
21- Activities: `opened`, `synchronize` (a push on the source branch), `closed` (`merged` true or false). Default: `opened`, `synchronize`, `reopened`.
22- `branches` filters the target; `paths` filters files changed between the merge base and the head.
23- A head that conflicts with the target makes no run.
24- Checks are on the head commit.
25
26## `pull_request_target`
27
28Same activities, filters and payload as `pull_request`, but the workflow comes from the **default branch** and runs on it. A head that edits the workflow changes nothing. Runs even on conflict.
29
30Stricter than GitHub: a merge request opened or pushed by an agent gets no secrets.
31
32Its cache is read-only and restores only default-branch entries.
33
34> **Warning:** never build, test or install the head's code in a trusted `pull_request_target` run (checking out `github.event.pull_request.head.sha` and running it). That leaks secrets: a "pwn request". Use `pull_request` to build a request's code. See GitHub's [Securely using pull_request_target](https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target).
35
36## `workflow_dispatch`
37
38```sh
39ermite workflow run <file> --repo <repo> [--ref <branch|tag>] [-f name=value …]
40```
41
42- Needs `ci:write`. `<file>` is a path or a name under `.github/workflows`. `--ref` defaults to the default branch. A disabled workflow (`ermite workflow disable`) is refused with `failed_precondition`.
43- Inputs are checked against the workflow (`required`, `boolean`, `number`, `choice`, `environment`). Up to 25 inputs.
44- A branch-limited token can dispatch only on its branches, and never gets a trusted run.
45- A job can dispatch with its own token when its `permissions:` give `actions: write`.
46
47## `schedule`
48
49- `cron` (five fields) with an optional IANA `timezone` (UTC by default). An invalid name fails the push's run.
50- Read on the default branch only; runs on its latest commit.
51- Missed minutes (server down) are not made up. Several matching entries start one run.
52- DST: a skipped time runs at the next valid time; a repeated time runs once.
53
54## `workflow_run`
55
56- `workflows: [<name>]`, `types: requested | completed`. `branches` filters the head branch of the triggering run.
57- Payload: `workflow_run` and `workflow`.
58- Chains stop after three levels.
59
60## `create` and `delete`
61
62- Start on a push that creates or deletes a branch or tag (also a merge with `--delete-branch`).
63- No filters; `[skip ci]` does not apply. A push of more than three tags starts none.
64- Payload: `ref`, `ref_type`, `pusher_type`, `repository`, `sender`; `create` adds `master_branch` and `description`.
65
66## Mirror events
67
68Not workflow triggers: `ermite watch` reports them when a [push mirror](mirror.md) changes health, once per incident.
69
70- `mirror.failed`: the mirror started failing or was paused. Payload: `repo`, `state` (`failing` or `paused`), `failure_class` (`diverged`, `auth_denied`, `remote_not_found`, `host_key`, `transient`, `internal`). In `ermite watch --json` they are `mirror_failed` (with `state`, `failure_class`) and `mirror_recovered`.
71- `mirror.recovered`: a failing or paused mirror pushed successfully. Payload: `repo`.
72
73The payload carries neither the remote URL, the reason nor the error detail; `ermite mirror status` shows the reason to repository admins.