CircleCI Ideas

Trigger workflows via CircleCI REST API

Currently REST API can only invoke the build step and does not properly support triggering steps within a workflow, or kicking off a full workflow. We would like the ability to use the REST API to:

1. kick off a step within a workflow

2. kick off an entire workflow

  • Avatar32.5fb70cce7410889e661286fd7f1897de Guest
  • Jan 31 2018
  • Shipped
API
  • Oct 3, 2018

    Admin Response

    This has been shipped. The documentation for triggering a workflow via the API is available here: https://circleci.com/docs/api/v1-reference/#new-project-build

  • Attach files
  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    7 Nov, 2019 07:26pm

    For reasons of backwards compatibility all workflows in a config run by default, so you will need to explicitly include/exclude those you want to run if you want to run only specific ones. This is known to be sub-optimal for cases where people want to configure many workflows and pick and choose which to run. If we see a lot of this kind of behavior we may add a way to switch the default behavior of running them all by default.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    7 Nov, 2019 01:50pm

    I experienced a similar thing. When using the V2 pipeline API to trigger a workflow it kicked off all the workflows for that branch unless I specified  `when: << pipelines.parameters.condition >>` in the workflow I wanted to kick off and `unless: << pipelines.parameters.condition >>` in the workflows I don't want to start. Bug or expected behavior?

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    1 Oct, 2019 09:01pm
    Hey Nathan, I am trying to use this v2 api to kick off my workflow. I have a question - how do I specify a branch when using this API? 

    I tried to to POST to https://circleci.com/api/v2/project/github/twilio/twilio-video.js/pipeline?circle-token=xxx
    with

    {
    "branch": "my_branch"
    "parameters": {
    "run_release_steps": true,
    "run_stable_only": true
    }
    }


    But saw that it kicked off the build against master. Where do I specify the branch in this new API? 

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    3 Sep, 2019 07:34pm

    We are in preview for our v2 API that provides parameters when triggering pipelines. Rather than passing workflow name directly we have the ability to run workflows based on a boolean parameter (with more expressive conditionality coming later). To run a particular workflow you can thus set up a boolean parameter and pass that. Preview documentation for doing that can be found here: https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/conditional-workflows.md

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    3 Sep, 2019 02:20pm

    https://circleci.com/docs/api/v1-reference/#new-project-build has nothing about triggering WORKFLOWS and simply returns 404 on 

    api/v1.1/project/:vcs-type/:username/:project/build

     More than that from its description it does not trigger arbitrary workflow, neither it can accept any parameters. So what's new? Can you please provide the doc that explains how to trigger ARBITRARY workflow by it's name with parameter. This was announced as implemented more than a year ago, still we are at the same place where we can't trigger any workflows with API.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    9 Aug, 2019 07:59pm

    Nathan, are there docs for the v2 conditional workflow endpoint? The regular API docs don't have any info on this new endpoint.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    23 Jul, 2019 02:07pm

    We are currently previewing our v2 API that has a new feature to allow conditionally running particular workflows based on parameters passed when triggering your pipeline. See this preview doc for more information: https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/conditional-workflows.md

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    22 Jul, 2019 06:58pm

    Seems like the link to the doc changes: https://circleci.com/docs/api/#trigger-a-new-build-by-project-preview

     

    Also, I don't see how to "kick off a step within a workflow" like it was suggested. This would be the most important thing for us.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    8 May, 2019 08:15am

    Any updates on this? Thanks

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    15 Feb, 2019 04:11pm

    Wanted to provide an update here, since it feels like there is little movement. This is very close to the top of our priority list and we hope to have it soon. It turned out to involve more work than expected, but we understand the need and are making it a goal to get this to you folks as soon as we can.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    5 Oct, 2018 09:17pm

    Thanks for the link. Though "shipped" is misleading as this is a part of preview which has limitations and so is not something that can be considered as released. Using label "in preview" would be more correct.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    3 Oct, 2018 06:04pm

    This got lost in the thread, but the documentation for triggering a build with workflows is here: https://circleci.com/docs/api/v1-reference/#new-project-build

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    3 Oct, 2018 09:33am

    This is marked as "shipped" though I can't find any announcements or documentation on that. So is it now available or not?

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    20 Aug, 2018 12:36am

    @Jóhann - make sure to vote on this Idea: https://circleci.com/ideas/?idea=CCI-I-208 -- we are looking at ways to allow you to filter based on files changed.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    19 Aug, 2018 08:35am

    @Nathan

    We're operating in a monorepo and are looking into ways to run a subset of the total workflow based on what code got changed. Our code structure is slightly complex so we'll have a script that determines what jobs need to run.

    One idea would be to have a checked in config.yml that only looks at the code changes, then generates a new config.yml file and kicks of a workflow using that config.yml using the API.

    Another one would be to have a checked in config.yml that only looks at the code changes and then kicks off a workflow using the API with build_parameters which would allow us skip jobs that we don't want to run (using the 2.1 config). I think this is probably the way to go if I understand the docs (https://github.com/CircleCI-Public/config-preview-sdk/blob/master/docs/conditional-steps.md)

    Any other approaches that you'd recommend? (maybe going off topic here, happy to move into email/DMs)

    I've yet to try the new API but does it work nicely with Github green/red lights? I.e. if I trigger a workflow from the API, will it post status updates to Github?

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    18 Aug, 2018 08:46am

    We are looking into letting you pass config as part of the build trigger, though there are security implications we want to work out first. We will be adding some answer to build parameters in the coming weeks. Curious to hear more specifics about your needs on both fronts if you care to share.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    18 Aug, 2018 07:16am

    This sounds great.

    I remember having seen somewhere that you'd be able to kick of an workflow with a custom config file but now I can't find any documentation on that. Is that a deprecated feature? Will the workflow always run from the config.yml from the revision?

    Also: what's the ETA for supporting build_parameters?

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    17 Aug, 2018 12:40am

    This is now live: https://circleci.com/docs/api/v1-reference/#new-project-build

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    7 Aug, 2018 10:46pm

    We are now testing this capability in the wild -- it requires turning on build processing under the Advanced settings on your project's Settings page. It will be in docs soon, but given how eager folks are I put together a little gist to explain how it works: https://gist.github.com/ndintenfass/a5a0a8b559057f29a63218e545033d3a#file-build-triggering-via-api-md

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    11 Jul, 2018 04:11pm

    Do we have a status on this? I've been waiting on this feature for about a yr now. I keep pushing back automation needs until this gets addressed. It would be nice to know when you think this will be available.

  • Load older comments