> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qawolf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger fields

> The fields of a trigger: deployment conditions, schedule, and the action that runs flows or Run AI.

Every trigger has a name, a paused state, deployment conditions or a schedule, and one action. It can also carry a `description` of up to 500 characters.

The app calls a trigger a [loop](https://docs.qawolf.com/loops/overview.md). The API creates loops that start on a deploy or a schedule, and that run flows or [Run AI](https://docs.qawolf.com/loops/run-ai.md). It can't create a loop that starts on a pull request or a QA Wolf event, and reports one with a `configuration.kind` of `advanced`.

## Deployment conditions

Every condition supplied must match. A trigger with no conditions fires on every deployment the workspace receives.

| Field | Description |
| - | - |
| `environmentIds` | Only fire for deployments to these environments. Mutually exclusive with `environmentPattern`. |
| `environmentPattern` | Only fire for deployments to environments whose name matches this pattern, such as `preview/*`. Mutually exclusive with `environmentIds`. |
| `deployTargetPattern` | Only fire for deployments whose deploy target URL matches this pattern. |
| `branchPattern` | Only fire for deployments of a branch matching this pattern. |
| `repositoryPattern` | Only fire for deployments from a repository whose `owner/name` matches this pattern, such as `acme/web` or `acme/*`. A deployment that names no repository never matches. |
| `servicePattern` | Only fire for deployments whose service matches this pattern. A deployment that names no service never matches a trigger carrying one, so adding a service pattern to an existing trigger silently stops it firing until your pipeline sends the field. See [Deployments](https://docs.qawolf.com/loops/deployments.md#what-a-deployment-carries). |

Patterns ignore case. In a pattern:

* `*` matches any run of characters, `/` included. `release/*` matches `release/1.2` and `release/1.2/hotfix`.
* `{a,b}` matches any one of its comma-separated options. `{main,hotfix}` matches either branch, and an option can hold `*`, as in `{release/*,hotfix/*}`.
* A leading `!` matches every value the rest of the pattern doesn't. `!{main,hotfix}` matches every other branch.
* Every other character matches only itself, `?`, `[`, `]`, `(`, `)` and `.` included. A brace with no comma, such as `{owner}`, is literal too.

A deployment with no deploy target, branch, repository or service never matches a pattern on that field, with or without `!`.

`environmentPattern` matches the name of the QA Wolf environment the deployment resolved to, not the name your pipeline sent. See [Deployments](https://docs.qawolf.com/loops/deployments.md#environment).

## Schedule

| Field | Description |
| - | - |
| `cadence` | `hourly`, `daily`, `weekly` or `monthly`. |
| `environmentId` | The environment the runs happen in, by id or alias. |
| `timezoneId` | The IANA timezone the schedule is read in, such as `America/New_York`. Required for every cadence, `hourly` included. It sets the wall clock `timeOfDay` is read against, and the day boundaries `dayOfWeek` and `daysOfWeek` are read against. |
| `timeOfDay` | When a daily, weekly or monthly schedule fires, as `HH:mm`. Required for those cadences. |
| `dayOfWeek` | The one day a weekly schedule fires on, named in lower case: `monday` through `sunday`. Required when the cadence is weekly. |
| `dayOfMonth` | The day of the month a monthly schedule fires on, from 1 to 28. Required when the cadence is monthly. |
| `daysOfWeek` | The only days an hourly or daily schedule fires on, as an array of lower-case day names. Name each day at most once; a repeated day is refused. An empty list is refused. Omitting it fires on every day. Refused on a daily schedule whose `every` is more than 1. |
| `every` | How many units pass between runs. Defaults to 1. An hourly schedule takes 1, 2, 3, 4, 6, 8 or 12, counted from midnight in `timezoneId`. A daily schedule takes up to 31, a weekly one up to 12, and a monthly one up to 12. |
| `startDate` | The date of the first run, as `YYYY-MM-DD`, for a daily, weekly or monthly schedule whose `every` is more than 1. Required then, and refused otherwise. Later runs repeat from it, so it decides which weeks or months are run weeks. It must fall on `dayOfWeek` or `dayOfMonth`. A past date is accepted. |
| `minuteOfHour` | Minutes past the hour an hourly schedule fires. Defaults to 0. |

> [!NOTE]
>
> `dayOfWeek` and `daysOfWeek` are different fields for different cadences. `dayOfWeek` is a single day and belongs to a weekly cadence, which fires on that one day. `daysOfWeek` is a list and belongs to an hourly or daily cadence, where it narrows an otherwise every-day schedule to the days you name. Neither field is accepted by the other's cadence.

A created schedule reports `nextScheduledAt`.

## Action

| Field | Description |
| - | - |
| `flowIds` | Flows named one by one. |
| `tagNames` | Every flow carrying one of these tags. Combines with `flowIds`. |
| `kind` | `createSuite`, the default, runs the flows named by `flowIds` and `tagNames`. `generativeSuite` makes the trigger a [Smart Smoke Suite](https://docs.qawolf.com/smart-smoke-suites.md): QA Wolf selects the flows from the pull request the deploy belongs to. `startAgent` makes it [Run AI](https://docs.qawolf.com/loops/run-ai.md): each firing starts a QA Wolf AI session that carries out `instructions`. |
| `instructions` | Required for `startAgent`: the task, up to 10,000 characters. Optional guidance for a `generativeSuite` selection. Refused on a `createSuite` action. |
| `investigateFailures` | Whether QA Wolf investigates failures in the runs the trigger creates. Defaults to `true`. |
| `runConcurrencyLimit` | How many runs of the resulting suite may execute at once. Sent as a string: a whole number from 1 to 1000 such as `"40"`, the literal `"unlimited"`, or a [concurrency expression](https://docs.qawolf.com/concurrency-limits.md#expressions) such as `"max(2, 4)"`. A number or expression replaces the environment's limit rather than capping below it, so it can raise the limit as well as lower it. `"unlimited"` is treated as unset, so the environment's limit still applies. Omit it to leave the environment's limit in charge. |

An action names at least one flow or tag, or is a `generativeSuite` or a `startAgent`. A `startAgent` action refuses `flowIds`, `tagNames`, `investigateFailures`, and `runConcurrencyLimit`. A `generativeSuite` action:

* Refuses `flowIds` and `tagNames`.
* Is only valid on a deployment trigger.
* Matches a deploy that isn't tied to a pull request, but doesn't run on it: the run outcome is `did-not-run` with reason `no-pull-request`. See [PR testing](https://docs.qawolf.com/deployment-testing/pr-testing.md) for what ties a deploy to its pull request.

## Paused

Send `isPaused: true` to `trigger.create` to create a trigger that never fires until `trigger.resume`. A paused trigger still fires by hand through `trigger.runNow`.

A paused trigger's conditions aren't checked. It still records a verdict for each deployment: `not-considered`, with reason `trigger-paused`.

Resuming brings back the same configuration. A resumed schedule's `nextScheduledAt` moves to its next upcoming slot, and slots missed while paused don't run.

## Reading a trigger back

* **`configuration`** — the deployment or schedule shape, for a trigger that runs flows. A trigger that runs AI, or that starts on a pull request or a QA Wolf event, reports `advanced` here.
* **`definition`** — the full configuration, a trigger that runs AI included, in the shape `trigger.update` accepts back. Absent for a trigger that starts on a pull request or a QA Wolf event.
* **`pausedReason`** — why QA Wolf paused a trigger that runs AI: `no-owner` when no person owns it, or `owner-left-team` when its owner is no longer a member. A person resumes it by selecting **Make me the owner** in the app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.