Submit Your Ideas

We want to hear from you - vote for the features and improvements you'd most like to see, or submit your own ideas if you don't find them already listed.

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
    03 Feb 22:16

    Aye was goid

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    17 Apr 12:51

    Triggering a complete workflow from the API is becoming imperaive for us, and we see ourselves forced to look into other CI solutions.

    Can you please share a schedule to when is this planned ?

    Thanks

  • Admin
    Nathan Dintenfass commented
    01 May 03:02

    This is very much on our radar. I can’t give firm estimates yet, but this is on the list of important things before our August deadline when we sunset our 1.0 service. 

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    04 May 20:07

    It would be useful to be able to do these things while preventing users from doing it in the UI too, which might work around code review processes we're implementing as CircleCI workflows.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    11 May 16:56

    Just hit this as well.  Seems a little crazy that this doesn't work.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    04 Jun 21:45

    +1. Use this for complex projects in Circle CI 1.0. We're actively migrating to Circle CI 2.0. Thought we were late to the show, but this is a blocker for us.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    07 Jun 13:15

    At the moment, even if it is not possible to trigger the entire workflow, it is possible to trigger a particular job that is referenced in the workflow. It is possible to re-implement the workflow (or implement a completely different one) by making the job call other jobs using the API. The mechanics are described in the documentation (https://circleci.com/docs/2.0/api-job-trigger/). 

    However, when a job is triggered using the API, context environment variables are not available to the job, even if the job references the context in the workflow definition (which sounds like a bug, if not an implementation one than definitely a requirements/design/user experience one). As a workaround, it is possible to define environment variables on the project level, but that defeats the whole point of context environment variables. I'd like to flag this issue here to make sure that it gets addressed as part of the effort to enable triggering workflows using the API. 

  • Admin
    Nathan Dintenfass commented
    07 Jun 16:14

    @Sergei Yes, this will be part of what gets addressed - you will be able to trigger the entire run of your config on a branch, including all workflows present. Contexts are resolved inside the workflow, and the job definition stands alone, so the old method isn't aware of the workflow. In the new triggering endpoint you will effectively be requesting to execute the entirety of the configuration on a given branch. 

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    20 Jun 10:19

    After I finished the migration from pipelines made by API calls to CircleCI 2.0 with lovely workflows and I found I cannot trigger a workflows via API. I'm feeling bad as I have to decide whether go back to v1 or reimplement a workflow with job API calls.

    It's very important and a major blocker now.

  • Avatar40.8f183f721a2c86cd98fddbbe6dc46ec9
    Guest commented
    11 Jul 16:11

    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.

  • Admin
    Nathan Dintenfass commented
    07 Aug 22:46

    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

  • Admin
    Nathan Dintenfass commented
    17 Aug 00:40

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

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

    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?

  • Admin
    Nathan Dintenfass commented
    18 Aug 08:46

    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
    19 Aug 08:35

    @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?

  • Admin
    Nathan Dintenfass commented
    20 Aug 00:36

    @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
    03 Oct 09:33

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

  • Admin
    Nathan Dintenfass commented
    03 Oct 18:04

    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
    05 Oct 21:17

    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.