Triggering workflow via API?

Does triggering a workflow from the API still not work?

The obfuscation and FUD around this crucial missing funtionality is startling. This feature has been requested as far back as 2017, and you now seem to vaguely claimed to support it, but I can not find a single example of anyone triggering a workflow via the API successfully. Support has suggested v2.1 of the api and referred me to the scant documentation below, but I can’t get it to work.

Is there a single working example of triggering a workflow via the API anywhere?

All I can get out of the 2.1 api is " “message” : “Project not found”", and all I can do with the 1.1 API is trigger jobs, not workflows.


I’m a customer, but not an API user, so can’t say whether this is supported.

Nevertheless, it may be worth wording this post more constructively. “FUD” is not just a buzz-word, it’s an active propaganda and disinformation strategy, and implies a great deal of wilful malice on the part of the accused. Perhaps you did not mean for your words to have the same force, but nevertheless, words mean how they are read, not how they are written - such is the curse of human communication.

We’re all tech professionals here, and I assume you are too. For some years I’ve worked by the dictum “you can insult me or get your bug/request responded to, but not both”. I hope you can get behind that - CircleCI employees are not setting out to hurt you.

@bmcgair I hear you - this is area we are prioritizing.

tldr: we have a 1.1 endpoint that triggers the workflow(s) in your config, though it has limitations some find onerous. We are also about to announce stability of our initial set of API v2 endpoints (currently in public preview), which include the ability to trigger pipelines with optional parameters you can use to drive specific workflows. The v2 API has preview docs up here: https://github.com/CircleCI-Public/api-preview-docs.

For those who want a more thorough explanation of the situation, strap in…:

In Sept 2018 we previewed the concept of “build processing” when we started to roll out orbs and the 2.1 config features. At that time we added an endpoint to the 1.1 API to trigger a build on a project:

https://circleci.com/docs/api/#trigger-a-new-build-by-project-preview

In code it would look something like:

curl -X POST https://circleci.com/api/v1.1/project/:vcs-type/:username/:project/build?circle-token=:token

That endpoint has been in production and documented since late 2018, and when you trigger work using it your workflow(s) will run. This is why we have said tbhat you can trigger workflows with the API. Admittedly, I see ways we could improve the description on that endpoint, and I’ll look into getting that done. However, in the next few weeks we’ll be encouraging people to move over to the new pipeline triggering endpoint in v2, so I strongly encourage anyone reading this in August 2019 to go try that first.

If you look through the preview docs to the v2 API you’ll see us referring increasingly to pipelines alongside workflows jobs. The v2 API will be the first major feature to reflect the new pipeline entity within the system. For those who have been playing close attention, you’ll notice we started talking about pipelines in March 2019 because use of the word “build” had become overloaded to mean both each job run inside your workflows and also used to describe the entire triggered run and its configuration. We found ourselves talking about builds inside of workflows inside of builds, so we formalized that you trigger pipelines that can contain one or more workflows that each orchestrate one or more jobs to be run on executors.

The new pipeline triggering mechanism in the v2 API is designed to address the two major shortcomings we’ve heard loud and clear from our developer community about the 1.1 endpoint for triggering jobs:

  1. In the 1.1 build triggering endpoint the return result is useless – that endpoint is a “fire and forget” way to trigger work on CircleCI. It does not return any identifier with which to get back the resulting workflows or jobs. In v2, the pipeline triggering endpoint returns a pipeline ID you can use to get information about it, including access to its workflows.

  2. In the 1.1 build triggering endpoint you can’t pass parameters – in our 1.1 API we have a way to POST to a project to trigger a job (aka a “build”), and that endpoint takes parameters that get injected into the job. In v2, we introduce pipeline parameters that are declared and used inside the configuration (note this is a change from how “build parameters” work in the 1.1 API). For more on how this work in v2 see https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/pipeline-parameters.md

For more on running conditional workflows using pipeline parameters see: https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/conditional-workflows.md.

For those who might wonder why the new pipeline triggering mechanism has more moving parts than the old job triggering endpoint, it’s because the old job triggering endpoint works only for individual jobs and cannot support any features of workflows or pipelines. An increasing number of projects are using those features, so we have been focusing on providing a reasonable API experience end-to-end. As of August 2019 we have well over half of all projects using pipelines, and that percent is climbing steadily). One of the underlying causes of some of the complexity in the v2 API is that the processing of pipelines happens in stages that are sometimes asynchronous. For instance, when you trigger a pipeline we immediately give you a pipeline ID, but the actual configuration processing happens after your trigger is received. And after the configuration processing your workflows are queued for execution. Once the workflows run the jobs are then created and dispatched to our execution systems. We run things with that kind of asynchrony to achieve reliability at the scale we’re now running. We’ll be eagerly listening to feedback on ways API v2 can be more expressive as we roll it out in the coming weeks.

2 Likes

Any update on timeline for this? API triggering of builds after deployments was something my team relied heavily upon, and had no clue that switching to use workflows would break this.

Even the fire-and-forget endpoint specified above would be awesome to have while the CCI team figured out where they want to go with new architecture. Thanks

The v2 triggering API linked above is in public preview and can be used now. We are doing a final review before declaring it stable in case we need to make breaking changes.

1 Like