Skip to content

GitLab

Triggering pipelines through the API (FREE)

Triggers can be used to force a pipeline rerun of a specific ref (branch or tag) with an API call.

Authentication tokens

The following methods of authentication are supported:

If using the $CI_PIPELINE_SOURCE predefined CI/CD variable to limit which jobs run in a pipeline, the value could be either pipeline or trigger, depending on which trigger method is used.

$CI_PIPELINE_SOURCE value Trigger method
pipeline Using the trigger: keyword in the CI/CD configuration file, or using the trigger API with $CI_JOB_TOKEN.
trigger Using the trigger API using a generated trigger token

This also applies when using the pipelines or triggers keywords with the legacy only/except basic syntax.

Adding a new trigger

Go to your Settings > CI/CD under Triggers to add a new trigger. The Add trigger button creates a new token which you can then use to trigger a rerun of this particular project's pipeline.

Every new trigger you create, gets assigned a different token which you can then use inside your scripts or .gitlab-ci.yml. You also have a nice overview of the time the triggers were last used.

Triggers page overview

WARNING: Passing plain text tokens in public projects is a security issue. Potential attackers can impersonate the user that exposed their trigger token publicly in their .gitlab-ci.yml file. Use CI/CD variables to protect trigger tokens.

Revoking a trigger

You can revoke a trigger any time by going at your project's Settings > CI/CD under Triggers and hitting the Revoke button. The action is irreversible.

Triggering a pipeline

To trigger a pipeline you need to send a POST request to the GitLab API endpoint:

POST /projects/:id/trigger/pipeline

The required parameters are the trigger's token and the Git ref on which the trigger is performed. Valid refs are branches or tags. The :id of a project can be found by querying the API or by visiting the CI/CD settings page which provides self-explanatory examples.

When a rerun of a pipeline is triggered, jobs are labeled as triggered in CI/CD > Jobs.

You can see which trigger caused a job to run by visiting the single job page. A part of the trigger's token is exposed in the UI as you can see from the image below.

Marked as triggered on a single job page

By using cURL you can trigger a pipeline rerun with minimal effort, for example:

curl --request POST \
     --form token=TOKEN \
     --form ref=main \
     "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"

In this case, the pipeline for the project with ID 9 runs on the main branch.

Alternatively, you can pass the token and ref arguments in the query string:

curl --request POST \
    "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline?token=TOKEN&ref=main"

You can also benefit by using triggers in your .gitlab-ci.yml. Let's say that you have two projects, A and B, and you want to trigger a pipeline on the main branch of project B whenever a tag on project A is created. This is the job you need to add in project A's .gitlab-ci.yml:

trigger_pipeline:
  stage: deploy
  script:
    - 'curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"'
  rules:
    - if: $CI_COMMIT_TAG

This means that whenever a new tag is pushed on project A, the job runs and the trigger_pipeline job is executed, triggering the pipeline for project B. The stage: deploy ensures that this job runs only after all jobs with stage: test complete successfully.

Triggering a pipeline from a webhook

To trigger a job from a webhook of another project you need to add the following webhook URL for Push and Tag events (change the project ID, ref and token):

https://gitlab.example.com/api/v4/projects/9/ref/main/trigger/pipeline?token=TOKEN

You should pass ref as part of the URL, to take precedence over ref from the webhook body that designates the branch ref that fired the trigger in the source repository. Be sure to URL-encode ref if it contains slashes.

Using webhook payload in the triggered pipeline

If you trigger a pipeline by using a webhook, you can access the webhook payload with the TRIGGER_PAYLOAD predefined CI/CD variable. The payload is exposed as a file-type variable, so you can access the data with cat $TRIGGER_PAYLOAD or a similar command.

Making use of trigger variables

You can pass any number of arbitrary variables in the trigger API call and they are available in GitLab CI/CD so that they can be used in your .gitlab-ci.yml file. The parameter is of the form:

variables[key]=value

This information is also exposed in the UI. Values are only viewable by users with the Owner and Maintainer role.

Job variables in UI

Using trigger variables can be proven useful for a variety of reasons:

  • Identifiable jobs. Since the variable is exposed in the UI you can know why the pipeline was triggered if you pass a variable that explains the purpose.
  • Conditional job processing. You can have conditional jobs that run whenever a certain variable is present.

Consider the following .gitlab-ci.yml where we set three stages and the upload_package job is run only when all jobs from the test and build stages pass. When the UPLOAD_TO_S3 variable is non-zero, make upload is run.

stages:
  - test
  - build
  - package

run_tests:
  stage: test
  script:
    - make test

build_package:
  stage: build
  script:
    - make build

upload_package:
  stage: package
  script:
    - if [ -n "${UPLOAD_TO_S3}" ]; then make upload; fi

You can then trigger a pipeline while you pass the UPLOAD_TO_S3 variable and the script of the upload_package job is run:

curl --request POST \
  --form token=TOKEN \
  --form ref=main \
  --form "variables[UPLOAD_TO_S3]=true" \
  "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"

Trigger variables have the highest priority of all types of variables.

Using cron to trigger nightly pipelines

Whether you craft a script or just run cURL directly, you can trigger jobs in conjunction with cron. The example below triggers a job on the main branch of project with ID 9 every night at 00:30:

30 0 * * * curl --request POST --form token=TOKEN --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"

This behavior can also be achieved through the GitLab UI with pipeline schedules.

Legacy triggers

Old triggers, created before GitLab 9.0 are marked as legacy.

Triggers with the legacy label do not have an associated user and only have access to the current project. They are considered deprecated and might be removed with one of the future versions of GitLab.

Troubleshooting

'404 not found' when triggering a pipeline

A response of {"message":"404 Not Found"} when triggering a pipeline might be caused by using a Personal Access Token instead of a trigger token. Add a new trigger and use that token to authenticate when triggering a pipeline.