Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

About the BITBUCKET_STEP_RUN_NUMBER Default Variable


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.

1 answer

1 accepted

1 vote
Answer accepted

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.


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

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?


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

Like Daniil Penkin likes this

@Daniil Penkin - 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.

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


Suggest an answer

Log in or Sign up to answer
Community showcase
Published in Bitbucket

New improvements to user management in Bitbucket Cloud 👥

Hey Community! We’re willing to wager that quite a few of you not only use Bitbucket, but administer it too. Our team is excited to share that we’ll be releasing improvements throughout this month of...

3,697 views 10 16
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you