# `Pipette.Trigger`
[🔗](https://github.com/tommeier/pipette-buildkite-plugin/blob/main/lib/pipette/trigger.ex#L1)

Buildkite trigger step that starts another pipeline.

Trigger steps allow one pipeline to kick off a build in a separate
Buildkite pipeline, optionally passing build parameters and
controlling whether to wait for completion.

## Top-level vs nested triggers

Triggers can be declared at two levels:

  * **Top level** — sibling to `group`. Renders as its own step on
    the Buildkite canvas. `depends_on` references must be top-level
    group names (validated at compile time).
  * **Nested inside a `group`** — listed alongside `step` entries
    under that group's `steps:` array in the emitted YAML, so the
    trigger appears as a child of the group's canvas card. Useful
    when a deploy is conceptually one logical phase that combines a
    cross-pipeline trigger and follow-up steps (e.g. tag/release).

Field semantics are identical for both. Resolution of `depends_on`
differs slightly: nested-trigger atoms are matched against sibling
step names first (resolved at compile time), then against top-level
group names (resolved at runtime). Strings always pass through as
explicit Buildkite step keys.

## Fields

  * `:name` (`atom()`) — unique identifier for this trigger
  * `:label` (`String.t() | nil`) — display label in the Buildkite UI
  * `:pipeline` (`String.t()`) — slug of the Buildkite pipeline to
    trigger (e.g. `"production-deploy"`)
  * `:depends_on` — atom (sibling step or top-level group), tuple,
    string (explicit Buildkite key), `Pipette.Optional`, or list mixing those
    forms
  * `:only` (`String.t() | [String.t()] | nil`) — branch pattern(s)
    restricting when this trigger fires
  * `:build` (`map() | nil`) — build parameters to pass
    (e.g. `%{message: "Deploy", env: %{DEPLOY_ENV: "production"}}`)
  * `:async` (`boolean() | nil`) — when `true`, don't wait for the
    triggered build to complete
  * `:skip` (`boolean() | String.t() | nil`) — skip the trigger; a string is
    displayed as the reason
  * `:key` (`String.t() | nil`) — explicit Buildkite step key.
    Auto-derived as `"<group_key>-<name>"` for nested triggers and
    `"<name>"` for top-level triggers if omitted.

## Examples

    # Top-level trigger
    trigger :deploy do
      label ":rocket: Deploy"
      pipeline "production-deploy"
      depends_on [:api, :web]
      only "main"
      async true
    end

    # Nested trigger (inside a group)
    group :deploy do
      label ":rocket: Deploy"
      only "main"

      trigger :rollout do
        label ":rocket: Rollout"
        pipeline "production-deploy"
        depends_on :api           # top-level group, resolved at runtime
        build %{commit: "${BUILDKITE_COMMIT}"}
      end

      step :tag_release,
        label: ":github: Tag & Release",
        command: "bash tag-release.sh",
        depends_on: :rollout      # sibling trigger, resolved at compile time
    end

# `t`

```elixir
@type t() :: %Pipette.Trigger{
  __identifier__: term(),
  __spark_metadata__: term(),
  async: boolean() | nil,
  build: map() | nil,
  depends_on:
    atom()
    | {atom(), atom()}
    | String.t()
    | Pipette.Optional.t()
    | [atom() | {atom(), atom()} | String.t() | Pipette.Optional.t()]
    | nil,
  key: String.t() | nil,
  label: String.t() | nil,
  name: atom(),
  only: String.t() | [String.t()] | nil,
  pipeline: String.t(),
  skip: boolean() | String.t() | nil
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*