Cascading Pipelines and Triggers

Often a project may involve more than one repository. Sometimes you might a change in one repository to trigger a pipeline in another repository. I can imagine various use cases for this when using VIPM packages or PPLs for managing dependencies. You may want the act of rebuilding the PPL or VIPM to trigger the pipeline for the calling code. My use case was actually much simpler.

I have a collection of GCLI Tools. Each tool resides in its own repository. However, there is one repository for all the documentation. This uses GitLab's Pages feature and mkdocs to publish the documentation. As part of that it scrapes the Readmes of the repository for each of the tools. I wanted to rebuild the main documentation when the readme for one of the tools changed. Otherwise, the documentation repo doesn't know if any of them changed so it doesn't know it needs to regenerate the documentation.

In GitLab, it was actually fairly straightforward. I just added the following job to the pipeline for each of my tools. It uses curl to trigger the pipeline for the documentation repo. It authenticates using a CI_JOB_TOKEN which is automatically generated by Gitlab. A simple rules section allows me to only trigger the documentation pipeline when the readme changes since I don't need to trigger it for every code change.

trigger_build_docs:   
  stage: build   
  script:
    - "curl -X POST --fail -F token=$CI_JOB_TOKEN -F ref=main https://gitlab.com/api/v4/projects/44733366/trigger/pipeline" 
  rules:
    - changes:
      - README.md

There is one other little trick. You need to go to the project that is receiving the Trigger and edit the Job Token Permissions in its CI/CD settings to grant permission to the triggering project or group of projects. In my case, I granted permission to the entire group so that any project/repo in that group can now trigger the documentation to rebuild using the above method. That screen also provides you with an audit log so you can see how often it is being triggered.

Need Help with GitLab Pipelines

If you need help setting up GitLab Pipelines we are about to release a new prerecorded CI/CD course. Be sure to check that out. It is based on our live workshop. If you'd like to inquire about setting up a workshop or have some unique CI/CD requirements, let's talk. Use the button below to schedule a call.