How to Trigger a Workflow via CircleCI API v2

Overview

CircleCI allows you to run multiple workflows within a single pipeline. However, there may be scenarios where you want to run only specific workflows based on certain conditions, such as branches, tags, or certain triggered events (scheduled_pipeline).

To trigger specific workflows in your CircleCI config, the ideal method is to use the "Trigger a new pipeline" endpoint. You can use a combination of pipeline parameters and conditional workflows to achieve this.

Triggering specific Workflows (Example):

Let's assume that you have the following workflows declared in your config.yml:

workflows:
  build:
    jobs:
      - job_a
  test:
    jobs:
      - job_b
  deploy:
    jobs:
      - job_c

You can declare the following pipeline parameters:

version: 2.1
parameters:
  run_workflow_build:
    default: true
    type: boolean

  run_workflow_test:
    default: true
    type: boolean

  run_workflow_deploy:
    default: true
    type: boolean

Note: setting the parameters' default value to "true" will allow the workflows to run when the pipeline is triggered by pushing commits.

Filtering Workflows using the "when" condition:

Once you have defined the pipeline parameters, you can now addwhen: conditions to the the workflows section as follows:

workflows:
  build:
    when: << pipeline.parameters.run_workflow_build >>
    jobs:
      - job_a
  test:
    when: << pipeline.parameters.run_workflow_test >>
    jobs:
      - job_b
  deploy:
    when: << pipeline.parameters.run_workflow_deploy >>
    jobs:
      - job_c

Multiple conditions for filtering a single workflow:

You can also add multiple conditions to filter a workflow (More examples are documented here).

workflows: 
  build:
    when: 
      and: 
       - equal: ["main", << pipeline.git.branch >> ]
       - equal: [true, << pipeline.parameters.run_workflow_build >>]
       - or:
          - equal: ["webhook", << pipeline.trigger_source >> ]
    jobs:
      - job_a

Triggering specific Workflows via the CircleCI API:

Using the above example, the cURL request to only run the test workflow would be (in the following requests your vcs-slug will be bitbucket or github depending on which VCS you use):

curl --request POST \
  --url https://circleci.com/api/v2/project/vcs-slug/org-name/repo-name/pipeline \
  --header 'Circle-Token: ***********************************' \
  --header 'content-type: application/json' \
  --data '{"parameters":{"run_workflow_build":false, "run_workflow_deploy":false}}'

Note: keep in mind that you have to use a personal API token; (project tokens will not work since they are not associated with a specific CircleCI User)

Optional Method:

For clarity, you could also pass the parameter corresponding to the workflow you wish to run. Doing so would have the exact same outcome as the above request because the pipeline parameters were declared with a default value set to "true":

curl --request POST \
  --url https://circleci.com/api/v2/project/vcs-slug/org-name/repo-name/pipeline \
  --header 'Circle-Token: ***********************************' \
  --header 'content-type: application/json' \
  --data '{"parameters":{"run_workflow_build":false, "run_workflow_test":true, "run_workflow_deploy":false}}'

References:

References:

Comments

Articles in this section