Trigger pipelines by using the API | GitLab (2024)

• Create a pipeline trigger token
• Trigger a pipeline
  • Use cURL
  • Use a CI/CD job
  • Use a webhook
    • Access webhook payload
  • Pass CI/CD variables in the API call
• Revoke a pipeline trigger token
• Configure CI/CD jobs to run in triggered pipelines
• See which pipeline trigger token was used
• Troubleshooting
  • 403 Forbidden when you trigger a pipeline with a webhook
  • 404 Not Found when triggering a pipeline
  • The requested URL returned error: 400 when triggering a pipeline

To trigger a pipeline for a specific branch or tag, you can use an API callto the pipeline triggers API endpoint.

If you are migrating to GitLab CI/CD, you cantrigger GitLab CI/CD pipelines by calling the API endpoint from the other provider’s jobs.For example, as part of a migration from Jenkins or CircleCI.

When authenticating with the API, you can use:

• A pipeline trigger token to trigger a branch or tag pipelinewith the pipeline triggers API endpoint.
• A CI/CD job token to trigger a multi-project pipeline.
• Another token with API access to create a new pipelinewith the project pipeline API endpoint.

Create a pipeline trigger token

You can trigger a pipeline for a branch or tag by generating a pipeline trigger token and using itto authenticate an API call. The token impersonates a user’s project access and permissions.

Prerequisites:

• You must have at least the Maintainer role for the project.

To create a trigger token:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > CI/CD.
3. Expand Pipeline trigger tokens.
4. Select Add new token
5. Enter a description and select Create pipeline trigger token.
   • You can view and copy the full token for all triggers you have created.
   • You can only see the first 4 characters for tokens created by other project members.

Trigger a pipeline

After you create a pipeline trigger token, you can use it to triggerpipelines with a tool that can access the API, or a webhook.

Use cURL

You can use cURL to trigger pipelines with the pipeline triggers API endpoint.For example:

• Use a multiline cURL command:

  curl --request POST \ --form token=<token> \ --form ref=<ref_name> \ "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline"

• Use cURL and pass the <token> and <ref_name> in the query string:

  curl --request POST \ "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>"

In each example, replace:

• The URL with https://gitlab.com or the URL of your instance.
• <token> with your trigger token.
• <ref_name> with a branch or tag name, like main.
• <project_id> with your project ID, like 123456. The project ID is displayedon the project overview page.

Use a CI/CD job

You can use a CI/CD job with a pipeline triggers token to trigger pipelines when another pipelineruns.

For example, to trigger a pipeline on the main branch of project-B when a tagis created in project-A, add the following job to project A’s .gitlab-ci.yml file:

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

In this example:

• 1234 is the project ID for project-B. The project ID is displayed on theproject overview page.
• The rules cause the job to run every time a tag is added to project-A.
• MY_TRIGGER_TOKEN is a masked CI/CD variablethat contains the trigger token.

Use a webhook

To trigger a pipeline from another project’s webhook, use a webhook URL like the followingfor push and tag events:

https://gitlab.example.com/api/v4/projects/<project_id>/ref/<ref_name>/trigger/pipeline?token=<token>

Replace:

• The URL with https://gitlab.com or the URL of your instance.
• <project_id> with your project ID, like 123456. The project ID is displayedon the project overview page.
• <ref_name> with a branch or tag name, like main. This value takes precedence over the ref_name in the webhook payload.The payload’s ref is the branch that fired the trigger in the source repository.You must URL-encode the ref_name if it contains slashes.
• <token> with your pipeline trigger token.

Access webhook payload

If you trigger a pipeline by using a webhook, you can access the webhook payload withthe 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.

Pass CI/CD variables in the API call

You can pass any number of CI/CD variables in the trigger API call.These variables have the highest precedence,and override all variables with the same name.

The parameter is of the form variables[key]=value, for example:

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

CI/CD variables in triggered pipelines display on each job’s page, but onlyusers with the Owner and Maintainer role can view the values.

Revoke a pipeline trigger token

To revoke a pipeline trigger token:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > CI/CD.
3. Expand Pipeline triggers.
4. To the left of the trigger token you want to revoke, select Revoke ().

A revoked trigger token cannot be added back.

Configure CI/CD jobs to run in triggered pipelines

To configure when to run jobs in triggered pipelines, you can:

• Use rules with the $CI_PIPELINE_SOURCE predefined CI/CD variable.
• Use only/except keywords, though rulesis the preferred keyword.

Additionally, the $CI_PIPELINE_TRIGGERED predefined CI/CD variable is set to truein pipelines triggered with a pipeline trigger token.

See which pipeline trigger token was used

You can see which pipeline trigger token caused a job to run by visiting the single job page.A part of the trigger token displays on the right of the page, under the job details:

In pipelines triggered with a trigger token, jobs are labeled as triggered inBuild > Jobs.

Troubleshooting

403 Forbidden when you trigger a pipeline with a webhook

When you trigger a pipeline with a webhook, the API might return a {"message":"403 Forbidden"} response.To avoid trigger loops, do not use pipeline events to trigger pipelines.

404 Not Found when triggering a pipeline

A response of {"message":"404 Not Found"} when triggering a pipeline might be causedby using a personal access tokeninstead of a pipeline trigger token. Create a new trigger tokenand use it instead of the personal access token.

The requested URL returned error: 400 when triggering a pipeline

If you attempt to trigger a pipeline by using a ref that is a branch name thatdoesn’t exist, GitLab returns The requested URL returned error: 400.

For example, you might accidentally use main for the branch name in a project thatuses a different branch name for its default branch.

Another possible cause for this error is a rule that prevents creation of the pipelines when CI_PIPELINE_SOURCE value is trigger, such as:

rules: - if: $CI_PIPELINE_SOURCE == "trigger" when: never

Review your workflow:rules to ensure a pipeline can be created when CI_PIPELINE_SOURCE value is trigger.