How to Trigger Another GitLab Project with a Tag in GitLab CI/CD

In GitLab CI/CD, triggering another project’s pipeline using a tag or branch can be useful for automating deployments, testing, and multi-repository workflows. In this post, we’ll explore how to trigger a pipeline in another GitLab project dynamically using GitLab’s built-in trigger keyword and the GitLab API.

Understanding `CI_COMMIT_REF_NAME`

Before diving into the pipeline configuration, it’s important to understand GitLab’s built-in environment variable CI_COMMIT_REF_NAME. This variable contains the current branch or tag that triggered the pipeline.

If the pipeline is triggered by a branch, CI_COMMIT_REF_NAME will be the branch name (e.g., main, develop).
If the pipeline is triggered by a tag, it will contain the tag name (e.g., v1.0.1).
If you specifically need only the tag name, use CI_COMMIT_TAG, which is only set when a tag triggers the pipeline.

You can debug this in a GitLab job:

debug_job:
  script:
    - echo "Current ref: $CI_COMMIT_REF_NAME"

Now, let’s look at two different methods for triggering another project.

Method 1: Using the `trigger` Keyword (For Same Group Projects)

GitLab allows triggering pipelines in another project using the trigger keyword. This method is useful when both projects belong to the same group and you don’t need advanced control over authentication.

trigger_another_project:
  stage: deploy
  trigger:
    project: path/to/project_name
    branch: $CI_COMMIT_REF_NAME  # This allows triggering for both branches and tags

Explanation:

project: path/to/project_name → The target project’s path in GitLab.
branch: $CI_COMMIT_REF_NAME → Dynamically uses the same branch or tag as the triggering pipeline.
No need for additional authentication if permissions are properly set.

Method 2: Using the GitLab API (For More Control)

If you need more flexibility (e.g., cross-group project triggering), you can use the GitLab API with curl to trigger another project’s pipeline.

Steps:

Create a Personal Access Token (PAT)
- Go to GitLab → Preferences → Access Tokens
- Generate a token with api scope
Modify .gitlab-ci.yml to trigger the target project

trigger_another_project:
  stage: deploy
  script:
    - curl --request POST --form "token=${CI_JOB_TOKEN}" \
      --form "ref=$CI_COMMIT_REF_NAME" \
      --form "variables[MY_VARIABLE]=example_value" \
      "https://gitlab.com/api/v4/projects/<TARGET_PROJECT_ID>/trigger/pipeline"

Explanation:

CI_JOB_TOKEN is a built-in GitLab token that allows secure authentication between projects.
ref=$CI_COMMIT_REF_NAME ensures the target project’s pipeline runs on the same branch/tag.
variables[MY_VARIABLE]=example_value allows passing custom variables if needed.
Replace <TARGET_PROJECT_ID> with the numeric ID of the target project (found in GitLab settings).

Choosing the Right Method

Use Case	Recommended Method
Projects within the same GitLab group	`trigger` keyword
Projects in different GitLab groups	GitLab API with `curl`
Need custom variables or advanced control	GitLab API with `curl`

Final Thoughts

Triggering another GitLab project dynamically can streamline your CI/CD workflows. Using $CI_COMMIT_REF_NAME ensures that pipelines are executed for both branches and tags, making your deployment process more efficient. If you need more control, using the GitLab API provides greater flexibility.

Do you have questions or other GitLab CI/CD use cases? Share your thoughts in the comments!