Support parameters when triggering a pipeline

The new "trigger a build by project" endpoint in practice triggers entire workflows and not singular jobs. In other words, it does not support specifying a job to trigger via build_parameters the way the other API job trigger does.

It would be greatly appreciated if the new endpoint could be made to support build_parameters so as to target particular jobs and not entire workflows. Our primary use case for wanting to trigger jobs outside of a workflow context via the API is ad-hoc mobile app submissions via our Hubot app in Slack. I imagine there would be other uses - there are plenty of opportunities for CircleCI-powered automation outside of a workflow context.

This would be especially helpful given that the other API job triggering endpoint is not supported when using the 2.1 configuration.

  • Jason Hagglund
  • Nov 14 2018
  • Candidate
  • Attach files
  • Guest commented
    November 16, 2018 08:32

    While I see the point of collecting use cases, in my world, a minor version upgrade which removes an existing capability ( is called a regression, not a new idea...

  • Nathan Dintenfass commented
    November 17, 2018 06:52

    There may have been a miscommunication because the endpoint in question was not removed. We added a new endpoint that behaves differently (and that we will be improving), but the old endpoint will work the same way they used to (with one important caveat -- the old endpoint cannot be used after you turn on build processing. The good news is that this is a temporary but unfortunate state because it forces a choice between sending these kinds of requests to CircleCI and using 2.1 config or the other features enabled by build processing. We are looking to provide an expanded build-triggering API that will be fully compatible with build processing and provide similar flexibility of the older endpoint for triggering individual jobs.

  • Jason Hagglund commented
    November 19, 2018 18:56

    Nathan - while it's true that the older API job trigger was not removed, it was rendered non-functional when moving from a 2.0 to a 2.1 config. That is *functionally* a regression, at least as experienced by those of us attempting to use the 2.1 config. I believe that is what the guest commenter was driving at with "a minor version upgrade which removes an existing capability." That the endpoint still exists isn't really a meaningful distinction to make when the very problem this feature request stemmed from is the inability to actually use said endpoint.

    I understand and appreciate the explanation of why the older build trigger isn't yet supported with 2.1 configs. The experience would have been much less jarring on my end had that explanation been offered up-front, preferably as an addendum to existing API documentation.

  • Anas El Barkani commented
    December 08, 2018 14:53

    the build_parameters is also useful if we want to inject additional env variables in a workflow build. we definitely need this

  • Martin Treurnicht commented
    January 15, 2019 19:12

    This such a huge oversight, i can't actually believe it. I spent so much time converting to 2.1 only to discover that the api doesn't work anymore. Now i have to decided if i'm willing to live without the triggers for a while or do i revert back to 2.0, i'm so irritated right now...

  • Patrik Ehrencrona commented
    January 21, 2019 14:28

    Migrating to 2.1 was a huge waste of time. Yes, it is clearly a regression.

  • Tyler Webb commented
    February 11, 2019 23:25

    100% need this for my specific use case

  • Bohdan Zhuravel commented
    February 15, 2019 08:52

    Also spent time migrating to 2.1 and had to move back to 2.0 because we need an API to trigger a single job (automated code review in our case).

  • Dana Reid-Vanas commented
    March 07, 2019 19:44

    This has been the state of affairs for nearly 4 months now, and it is not well documented or communicated. Can we get a timeline for when this will get resolved?

  • Greg Zapp commented
    March 16, 2019 23:37

    Really need this for hooking up downstream project builds; need to pass upstream information in such as tag, build number, etc.

  • Fabrice Ongenae commented
    April 01, 2019 14:07

    Hello, we are also waiting for this functionality since november. Is it possible to have an ETA? Thank in advance.

  • Zach Whelchel commented
    April 08, 2019 13:54

    Would love to hear an update on this. We build a white label app and would love to be able to supply build parameters to several instances to be able to update all of our white label apps. To do this we need to be able to pass in build_parameters. Any ETA? Or a different way to achieve our goal?

  • Nathan Dintenfass commented
    April 08, 2019 17:56

    Our plan is to provide a slightly different mechanism for injecting variables. Now that our "build processing" is called "pipelines" we'll be launching a v2 of our API that allows triggering a pipeline with parameters. However, unlike the old job triggering endpoint, we won't be injecting those parameters directly into your job as environment variables. Instead, we'll make those variables available during config processing and force them to be declared in config. This is both safer and more deterministic. It will also let you use pipeline parameters in config structures such as working directory or to set the tag on an image, etc. You can view a preview of our plans on this front here: 

  • Leonardo Fernandez commented
    April 08, 2019 20:31

    Are there any timelines for when the API v2 will be released?

  • Nathan Dintenfass commented
    April 09, 2019 01:45

    We'll be rolling out v2 one endpoint at a time, starting with `GET /workflows/:id` and `GET /workflows/:id/jobs`. We'll be updating this repo as we roll things out in preview:

  • Alex Capt commented
    April 15, 2019 16:24

    I ended up again on the same "issue" after another 2.1 upgrade. I just forgot about it (or secretly hoped it was fixed).

    This "new idea" (considered by all your customers as a regression) has be raised in Nov 2018. There are multiple forum entries like and multiple of your customers are stuck (and frustrated) with their 2.1 upgrade.

    There is a "on roadmap" label on the idea, why are you not be able to provide a clear status and an ETA ?

    The public API documentation is still not clear about the real working 2.0 vs 2.1 capabilities while the git repo you shared does not contain anything useful.

  • Martin Treurnicht commented
    May 28, 2019 21:37

    I've been waiting for this to be fixed since November last year, still no news. I'm at the point now where I either want an ETA on when we can expect these features or I'm switching to something else... I just don't understand what could be taking so long, this is such a trivial feature, it's basically just fixing a regression issue. I would've expected it to take 1-2 months max. Without this we can't upgrade to 2.1, being able to trigger other jobs from a build workflow is such a fundamental part of what a build pipeline does, i'm actually shocked that more people aren't complaining about this

  • Nathan Dintenfass commented
    May 28, 2019 21:59

    I feel you on how long it has taken -- this has taken longer than we originally anticipated. That said, adding parameters to the triggering of pipelines is next up for us. Keep in mind it will work a bit differently than it did in 1.1, but you should be able to do functionally all of the same things (and more) with the new pipeline parameters. The best place to stay up to date is still

  • Tobias Meixner commented
    July 07, 2019 07:45

    Another month is gone - is there any update on this?

    Thank you.

  • Nathan Dintenfass commented
    July 09, 2019 15:29

    The pipeline parameters are now live in preview, per the links posted above. The direct link to preview docs  the parameter passing is:

    Feel free to post back here, or post Issues on that repo if you have feedback.

  • Robert Cooper commented
    July 16, 2019 19:01

    With the Build Pipeline parameters now live, is it possible to use the Pipeline params as the `parallelism` argument value?



      parallelism: << pipeline.parameters.parallelism >>

      working_directory: ~/my/dir/




    When trying ths, I get the error:

    # |   1. [#/jobs/manual_build/parallelism] 0 subschemas matched instead of one
    # |   |   1. [#/jobs/manual_build/parallelism] expected type: Number, found: String
    # |   |   |   SCHEMA:
    # |   |   |     type: integer
    # |   |   |   INPUT:
    # |   |   |     << pipeline.parameters.parallelism >>
    # |   |   2. [#/jobs/manual_build/parallelism] string [<< pipeline.parameters.parallelism >>] does not match pattern  *<< *parameters.([^ ]+) *>> 


    As far as I'm aware, I could set this as a job parameter, but would be unable to pass that parameter in to the API request. Is there a way around this issue?

  • Nathan Dintenfass commented
    July 16, 2019 22:41

    It is intended to work -- but I can reproduce what you're seeing, so I'm filing a bug internally. (CIRCLE-19445)

  • Nathan Dintenfass commented
    July 31, 2019 05:42

    The above bug using a parameter as the value of parallelism should now be fixed.

  • Richard Clayton commented
    August 01, 2019 14:53

    Hey, I just wanted to confirm the status -- is this still "on roadmap".  I noticed the last comment that it is "in preview".  Does that just mean the suggested API is being displayed for dev feedback?

  • Nathan Dintenfass commented
    August 01, 2019 17:55

    The API documented in the preview is live and available for use. We don't anticipate making changes, but until we fill out the rest of the v2 API we'll keep it in "preview" status. I encourage you to give it a try, and let us know what you think. Best way to give feedback for now is to submit issues on that GH repo. The pipeline parameters specifically are documented here:

  • Kristofer Borgström commented
    25 Mar 07:47

    With this API there is still no way to trigger a single job via API (with or without parameters) unless you:
    * Create a workflow for every single job AND introduce parameters to not run any other workflow
    * Set up branches for each job with a seperate ci config

    Neither workaround is feasible in my opinion