Overview

You may have situations where a specific workflow in one of your projects should trigger a new build in a different project. As an example, maybe an update to your blog project needs to kick off a new build in your website project to ensure everything is up to date.

Adding a step to trigger a pipeline in a different project

You can accomplish this via a run step that sends an API call to trigger a new pipeline. You will want to generate a personal API token and store it as an environment variable within the project the run step will be on.

Then once that is done you will add this run step to your config of that project:

- run:
  name: Kick off new pipeline
  command: |
    curl --location --request POST 'https://circleci.com/api/v2/project/(vcs)/(org)/(project)/pipeline' \
    --header 'Content-Type: application/json' \
    -u "${API_TOKEN}:"

In the above snippet, you will need to update (vcs) to github or bitbucket, (org) to your Organization, and (project) to the name of your project.

Once this has been done once the first project reaches the run step above it will start the second pipeline automatically as long as the settings are correct including the API_TOKEN.

NOTE: You will receive a "project not found" response from the CircleCI API endpoint if the user token does not have the correct permissions or has not been added as an environment variable 

What if I'm using a GH Apps integration?

The steps for achieving this with a GH apps integration are relatively the same. The only difference is that instead of "generate a personal API token and store it as an environment variable", you should instead go to this page and set up an inbound webhook. You can then replace the call to the v2 trigger pipeline API (as a call to the v2 API will not work with GH Apps) with the inbound webook URL that you just generated. You should store the secret as an env var like you would for the personal API token.

curl -X POST -H "content-type: application/json" '(insert-generated-URL-here)?secret=${WEBHOOK_SECRET}'

How do I know if I'm using GH Apps integration?

Since determining what type of integration you have will determine which method to use, here is an article we have created that will help you determine what type of integration you are using:

• Is my project setup using GitHub OAuth or GitHub Apps?

Additional Resources: 

• Creating a Personal API Token
• Set an environment variable in a project
• CircleCI v2 API