Rest Api to start a stage for build

Question

According to the Bamboo REST api I can trigger a build by using

curl -u {user:pwd} -X POST https://{server}/rest/api/latest/queue/{build-plan}?stage&executeAllStages

I have a build plan with two stages (CI Build, IntegrationTest) and want to trigger the second stage. The IntegrationTest stage is a manual stage.

So I tried   
    curl -u {user:pwd} -X POST https://{server}/rest/api/latest/queue/{build-plan}?stage=IntegrationTest&executeAllStages=false

As a result, the plan executes the CI Build stage, and after the completion also the IntegrationTest stage. I assumed that the CI build phase would be skipped by the executeAllStages=false parameter. Is that not the supposed behavior?

Guan Wee Loo · Answer

Hi ,

This is really useful.  I noticed the following though:

If stage=Second was already executed before and I do this:

https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?stage=Second&executeAllStages=false

Stage 3 will be executed though the expectation is nothing will happen since stage 2 has completed and executeAllStages is set to false

Steffen Opel [Utoolity] · Answer

The Bamboo REST API and esp. its documentation leaves a lot to be desired unfortunately. Regardless, based on the docs for /queue/{projectKey}-{buildKey}-{buildNumber : ([0-9]+)}?stage&executeAllStages, I've been able to trigger a build with one automatic and two manual stages in various ways as follows:

* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS => runs first automatic stage only
* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?stage=Second => runs up to and including the second manual stage, but excludes the subsequent third stage
* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?stage=Third => runs up to and including the third manual stage and thus yields a complete plan build

This matches the documented behavior for parameter 'stage':

name of the stage that should be executed even if manual stage. Execution will follow to the next manual stage after this or end of plan if no subsequent manual stage

So you can achieve your goal as long as you know the name of the last stage in the plan. This is the one limitation that 'executeAllStages' is supposed to address it seems. And in fact this seems to work just fine if used standalone as follows:

* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?executeAllStages=true => runs up to and including the third manual stage and thus yields a complete plan build
* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?executeAllStages=false => runs automatic stages only
* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?executeAllStages => also runs automatic stages only, i.e. defaults to false then

This also matches the documented behavior for parameter 'executeAllStages':

enforce executing all stages in a plan, even if defined as manual stages. Execution will follow and include latest stage, unless some stage will fail.

Finally, your scenario using both parameters also seems to work correctly, albeit with a subtle twist:

* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?stage=Second&executeAllStages=false => runs up to and including the second manual stage, but excludes the subsequent third stage
* https://{{host}}/bamboo/rest/api/latest/queue/TST-NMS?stage=Second&executeAllStages=true=> runs up to and including the third manual stage and thus yields a complete plan build

So it seems that an explicitly specified stage is evaluated and obeyed first, yet 'executeAllStages' still applies thereafter, which seems to make sense once there is more than one subsequent manual stage involved.