How to Trigger a Workflow via CircleCI API v2

Trigger a Workflow

CircleCI API (v2) doesn't currently provide a dedicated endpoint to specifically trigger a new workflow.

However, it is still possible to trigger a specific workflow using the "Trigger a new pipeline" endpoint. It requires some modification to your config.yml, and the use of pipeline parameters, as well as, conditional workflows.

Example

If you have the following workflows declared in your config.yml:

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

You will need to 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.

And modify the workflows section as follows:

workflows:
  version: 2
  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

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 are currently not supported on CircleCI API (v2).

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:

Trigger a Workflow

Example

References:

Comments

Articles in this section