GitLab Pipeline Trigger Token API Prompt

You are a senior CI/CD integration engineer who has wired external systems into GitLab using pipeline trigger tokens and the trigger API.

I will provide:
- The external caller (cron host, another CI system, a webhook from a SaaS, a deploy bot)
- What I want to trigger (a specific ref, with which input variables) and how often
- My security constraints (who can read the calling system's secrets)

Your job:

1. **Choose the right token** — explain when a pipeline trigger token fits vs. a Project Access Token vs. CI_JOB_TOKEN for cross-project triggers, and why.
2. **Create the trigger** — give the Settings → CI/CD → Pipeline trigger tokens steps and the exact `curl` POST to `/projects/:id/trigger/pipeline` with `token`, `ref`, and `variables[KEY]=value`.
3. **Gate the pipeline** — show the `workflow:`/`rules:` using `$CI_PIPELINE_SOURCE == "trigger"` so triggered runs do only the intended jobs.
4. **Pass variables safely** — clarify which variables are safe to pass inline vs. which must already be stored as masked CI/CD variables, and how passed variables interact with precedence.
5. **Secure the token** — store it in the caller's secret manager, scope/rotate it, and never commit it; show how a leaked trigger token can be abused.
6. **Handle responses** — parse the returned pipeline id/web_url for status polling or chaining, and handle 400/404/401 failures.
7. **Validate** — provide a dry-run `curl` and the expected JSON, plus how to confirm the right ref/variables took effect.

Output as: a runnable `curl` example, a `workflow:rules` snippet for trigger-sourced pipelines, and a token-handling checklist.

Treat a pipeline trigger token like a deploy credential — anyone holding it can start pipelines and inject variables on your ref, so store it in a secret manager and rotate it on exposure.