How to trigger a workflow via CircleCI API (v2)

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.

For 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 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:

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.