About the BITBUCKET_STEP_RUN_NUMBER Default Variable

[ktomk]

I'd like to learn more about the `BITBUCKET_STEP_RUN_NUMBER` default variable in the Atlassian Bitbucket Cloud Pipelines Plugin.

Whenever I access it, its' value is the integer number "1".

The description on the Variables in pipelines page gives the following information:

BITBUCKET_STEP_RUN_NUMBER - Number of times a step has been executed per pipeline.

What I'm interested in specific is that I ask myself how it could have any other number than "1" because as far as I understand it, a step within a pipeline can only be executed once. But then why should there be a variable for it? So therefore I somehow have the feeling I'm missing some interesting details here, so maybe someone else might have an example where that variable has a different value than "1" or what a use-case could be.

[Daniil Penkin · Accepted solution]

Hello @ktomk,

When a pipeline fails, there's an option to rerun just the failed steps. If you trigger that, BITBUCKET_STEP_RUN_NUMBER variable for the steps being rerun will be greater than 1, depending on how many times they've been rerun. This is so that your script can use the fact that it failed previously, should it need that information for retrying.

Hope this helps. Let me know if you have any questions.

Cheers,
Daniil

[ktomk]

But it can not be used to just obtain the number of re-run regardless if there was an error? Is that correct?

[Daniil Penkin]

There's in fact no way to rerun a step that succeeded. If your whole pipeline succeeded, you'll only see an option to rerun entire pipeline, but that in fact runs new pipeline at the same commit with the same configuration.

If any steps in your pipeline fails, you can rerun only failed steps — this is what will increment BITBUCKET_STEP_RUN_NUMBER variable visible from steps being rerun.

So, back to your question: only failed step can be rerun (and your pipeline has to have more than one step for that option to be available), and BITBUCKET_STEP_RUN_NUMBER will be larger than 1 only for failed steps being rerun.

Does this make sense?

Cheers,
Daniil

[ktomk]

@Daniil Penkin Ah okay, now I get it. It's per that one run. Otherwise it is a new run, and indeed the whole pipeline is re-run. I was just trying with a very small example which did never fail so could not fully reproduce.

This makes total sense now. Thanks a lot for the answer and the clarification!

[ktomk]

@Daniil Penkin https://bitbucket.org/ktomk/atlascode/commits/1039277bd417d95aa91fff8cf258d2f515693fdd - I can't file a PR in the repo, just some schema changes you might be interested in. It for sure needs edits in the descriptions.

[Daniil Penkin]

That's awesome, thanks for your contribution! I'll find some time to take them into Atlascode if you don't mind.

Cheers,
Daniil

[Shubham]

@Daniil Penkin 

I have one query wrt this BITBUCKET_STEP_RUN_NUMBER variable

There are some steps configured as deployment, where after running the step, we again get an option to trigger re-deploy like below.

In below case also, will this no increment if I re-deploy?

I can trigger that re-deploy multiple times, Will it increment every time?

Or will it increment in case of failed step only?

[Daniil Penkin]

Hello @Shubham,

BITBUCKET_STEP_RUN_NUMBER will be incremented on each redeploy in this scenario, no matter whether the deployment was successful or not.

In my original reply I incorrectly stated that only a failed step can be rerun – in fact, you're right, redeploy effectively reruns a successful step (or multiple steps, should they be part of a deployment stage).
Nevertheless, BITBUCKET_STEP_RUN_NUMBER reflects the number of times a step has been triggered and ran.

Cheers,
Daniil