Creating Manual CircleCI Workflow Triggers

CircleCI workflows can be defined in two ways: the regular workflow, where the workflow is triggered on each and every commit, and the scheduled workflow, which is triggered according to the specified schedule.

The problem with workflows is that they cannot be targeted directly for API and web interface triggers! We can only trigger a pipeline for a project branch, and when we do so all the non-scheduled workflows are run.

So how do we configure a workflow that only runs when we trigger it manually?

The answer is surprisingly simple: we create a regular workflow that runs on each commit, but we add a when clause to ensure that it only runs when we provide it with a specific parameter.

Conversely, for workflows that we only want to run when commits are pushed, we add a when clause to ensure that they only run when such parameters are not provided.

  1. Define the trigger parameter at the top of the .circleci/config.yml file.
  2. Define a workflow with a when clause.
  3. If desired, pass the parameter through to the job(s) the workflow calls.

Once your workflow is configured, you can now trigger it via the “Trigger Pipeline” button on the project / project branch page of the CircleCI web interface, or you can send the following request:

Hope this helps!



Adam Fisher / fisher king (@therightstuff)

Software developer and writer of words, currently producing a graphic novel adaptation of Shakespeare's Sonnets! See for details.