Poll: how are you using CIRCLE_BUILD_NUMBER?


NOTE: this will only be interesting to people who actively use the value of CIRCLE_BUILD_NUMBER in their config.yml.

With the recent change in the UI, where jobs are now under “Jobs” instead of “Builds”, we’re turning our attention to addressing some of the other places the word “Build” still refers to the run of a job in CircleCI 2.0. One such place is among the handful of environment variables we add to your execution environment, including:


I’m seeking a bit of input from the community to get a feel for how people are using CIRCLE_BUILD_NUM in particular. We are very cautious to make any change to behavior of our built-in environment variables, but in this case the name CIRCLE_BUILD_NUM is really better thought of as CIRCLE_JOB_NUM. One possibility under consideration is to add CIRCLE_JOB_NUM to behave as CIRCLE_BUILD_NUM does today, then change CIRCLE_BUILD_NUM to increment each time you request a build for execution rather than for each job run within that build. If we did that, it would make a subtle change to the behavior of CIRCLE_BUILD_NUM in that it would now be the same value across all jobs within a workflow run (or even across workflows if you have more than one in your configuration) rather than a different value in every job that is run within a workflow.

Please answer the poll below (also leave a reply if you have questions or other comments).

  • I use it, but I don’t care if it changed behaviors to be the same number for all jobs across my workflow run
  • I use it, and I rely on it being a different number in every job of my workflow run
  • I use it, but neither of the above apply to me

0 voters


If CIRCLE_BUILD_NUM becomes identifier of the whole workflow (i.e. same for all jobs) I guess it would also be good to make CIRCLE_BUILD_URL point to the URL of the UI workflow page (I think it is currently https://circleci.com/workflow-run/$CIRCLE_WORKFLOW_ID)?