Release version column -- how to set

in the releases tab, there’s a column: Release version which is always empty (last column in screenshot):

How can I set this?
I tried it with balena tag via CLI but this (as the command says) only sets a tag.
How can I set a custom release version?



Have you pushed any code to this device yet? Is this a freshly provisioned device running no application?

yes of course. Already hundreds of releases for this application.
I just came across the (to me new) column and I was wondering on how to set it. It’s currently empty for all deployed releases (across all my apps).

Hi @fritz, currently we only support using the release version if you are using a balena.yml contract as described here. We are working on a revamp of the release versioning system, I don’t have a timeline to share at the moment but it is very close to completion.

@tmigone Is there any update on the release versioning system? This would be super-useful for a project my team is working on right now. Trying to determine whether we should go down the path of generating our own version numbers or wait for this feature.

Hi @mike-dean, @fritz, actually most of the new release versioning system is already deployed to production! We haven’t yet announced it because we are working on one last piece that would help tie everything together, GitHub actions. Once that is done we will release proper documentation, blog post and officially launch the feature (my guess here is it’s week(s) away if we don’t hit any roadblock). I’ll try to provide a brief overview of how it works so you can assess wether it’s something useful for your use case, and as I said most is in balenaCloud already so you can check it out too (for example release page on the dashboard already shows the updated version, and if you use the SDK or hit the API release resource you’ll see the new fields too).

The gist of the new system is to decouple release version from source code version. When building a project there are time sensitive steps that affect the build outcome, so built artifacts can differ even if they originated from the same source depending on when they were built. We wanted a way to reflect that with the new release versioning.

You can specify the version of a release that our dashboard presents, by adding a balena.yml file with a version field in the top level folder of your project, in which you run the balena push, git push or balena deploy commands to create a new release. For example a balena.yml could look like:

type: sw.application
version: '1.2.3'

The version field at the moment has to be in a 3-digit semver format and will be stored in the release.semver field in our backed. On top of that backend then will append the +revN for subsequent releases with the same version. The combined result of the base version you provided along with the autogenerated revision (in case the same version was used again earlier) will be available on the release.version field stored in our backend.

For example:

  • Pushing project with version: 1.2.3 will result in a release with version 1.2.3+rev0 (UI will hide the +revN part if revision is 0).
  • Pushing the same project with same version: 1.2.3. will result in 1.2.3+rev1 and so forth.
  • If you push a project without balena.yml it will start off at 0.0.0

On top of this, we introduced the concept of “draft” releases. Draft releases might be created for testing, or by CI systems and won’t interfere with the + revN system. Instead draft releases will use timestamp to be uniquely identifiable: 1.2.3-12345678. Draft releases can be created with the --draft flag.

Again, most of this (if not all) is already in production but please wait for an official announcement in the coming weeks before building on top of if as things might change until then.


Happy to answer any questions you might have, and stay tuned for an announcement about this coming soon.

Hi @tmigone
thanks for introducing this. Quick question before I’ll give it a try:
what’s the supposed content of “type”
In your example it’s
type: sw.application
Is this a hardcoded value or what to put there? Thanks
Also it would be cool to have somehow the git commit hash to be included (automatically).

@tmigone Another question:
do I get this information from the supervisor API somehow?
Right now, with
curl -X GET --header "Content-Type:application/json" "$BALENA_SUPERVISOR_ADDRESS/v1/device?apikey=$BALENA_SUPERVISOR_API_KEY"
I only the the commit Id, would be great to enhance this with information about the more readable release version info.
Or, if already implemented: which supervisor version would deliver this information?

Hello @fritz to get the version of the release you can use this if i’m not wrong.

To learn more about the balena.yml feel free to check here. The type field diferentiates among applications and blocks.

Let us know if this works for you!

Hi @mpous
thanks, but I’d need to get this information on the device somehow, not going via balenaCloud. Any chance?
Thanks and Cheers,

oh ok @fritz sorry that i didn’t understand! I will ask into the team. I was testing myself if it appears as an environment variable here but it’s not the case yet.

We will keep you updated

BTW it would be interesting to understand your use case and versioning system that you are trying to build. Plus why you can’t query the api from the device. Could you please tell us more (if possible)?

the usecase is that we are able to give field technicians access to the public_url and they have a setup guide there, when installing our devices. It would just be handy to display the deployed SW version if in any case there are issues to have it at hand.
Also, we would include this information into our logging system, if there’s an issue on the device and it sends an error message to the backend, we could include this information.


Haha, and btw. the first thing I check, as well have been the env vars :wink: But didn’t find it there, so I looked up the API, and then I came here :wink:

Hey @fritz, we’ve confirmed now that the release info like the version are not available directly on the device or the supervisor without involving balenaCloud or the API in some way.

However, it’s a good idea and I’ve updated a pattern internally with your use case so we can track it as a possible improvement in the future!

Thanks this is exactly what I was looking for as well.

I’ve been tracking this GitHub - balena-io/balena-ci but did I miss the official announcement?

Hey, we haven’t made any announcements regarding that action yet but will be very soon! Feel free to use it and give us any feedback. It’s stable now but just slowly rolling it out internally and adding whatever touches the team thinks of before releasing v1.0.0.

What timeline is “very soon”? :slight_smile:

Haven’t seen this topic yet, but it’s great that human-readable versions are now supported!
Is this also supported for openBalena or is this a balenaCloud solution only?