nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Bitbucket Pipeline Labels

plussier_hplmja

Hi all,

In this YouTube! video by Edmund Munday, Edmund mentions building a dynamic pipeline generated entirely by a `bitbucket-pipelines.yml` file which contains nothing but a `labels:` block which is a mere 7 lines of yaml.

Does anyone know where the Bitbucket documentation for the `labels:` section is? I can't find any mention of it in the Pipeline Reference docs here:

https://support.atlassian.com/bitbucket-cloud/docs/global-options/

And in this community post, @Edmund Munday mentions:

(to be totally honest, "labels" as a feature are still technically undocumented and not "officially" released haha).

But that was from almost exactly a year ago. So I'm wondering if labels

is officially supported yet?
has any documentation anywhere describing use, limitations, capabilities, use-case or code examples, etc.

I did find this one brief mention in the Forge Reference for Dynamic Pipelines:

https://developer.atlassian.com/platform/forge/manifest-reference/modules/bitbucket-dynamic-pipelines-provider/#labels

But other than mention it's a free-form yaml block restricted to 10K in size it doesn't help me much. I'm trying to figure out how to use it, so would love to see example code that parses the labels and does things with them based on values, etc.

Thanks!

Paul

Accepted answers

Ben

Hi @plussier

I've just reached out to our PM team for Bitbucket Cloud and will get back to you shortly

Cheers!

- Ben (Bitbucket Cloud Support)

Daniil Penkin

Here's is a shortened version of the clarifications from the support ticket mentioned above to ensure this question remains useful for anyone coming across it later:

Labels are officially supported. The documentation could be better indeed, we plan to improve it in the future.
There's a 10 KB limit on the total size of labels map serialised into JSON. Besides that, there are top-level label namespaces reserved for future and/or internal use, namely atlassian, as of now. This list might be extended in the future, but we'll do our best to make such changes unnoticeable.
- The snippet from the webinar video mentioned above is just an example of labels map used by an internal Dynamic Pipelines provider used within Atlassian.
What's most important about labels map is that it is passed to the Dynamic Pipelines provider as is, and the provider can leverage labels to its advantage. Again, sadly there are no sample scenarios for this in our documentation just yet, and we will consider adding them.
Finally, parsing labels logic depends on the provider implementation:
- Simple Forge function takes in a request object, and labels will be under its pipelines_configuration property, so request.pipelines_configuration.labels would be the way to access labels.
- In case of Forge Remote app, the backend can use any language or framework, and label parsing from the POST payload would rely on whatever tools that stack provides.

Cheers,
Daniil

All comments

Ben

Hi @plussier

I've just reached out to our PM team for Bitbucket Cloud and will get back to you shortly

Cheers!

- Ben (Bitbucket Cloud Support)

plussier_hplmja

Thanks, @Ben !

Ben

Hi @plussier

Based on my research - labels are still not officially supported and there is no external documentation at this point in time - I can share with you some information about them but I'm still waiting for a response from our PM team regarding the feature itself and when there might be changes related to this.

Description

Labels allow you to store arbitrary data inside your Pipelines configuration that you can use for things like automation and logic implementation with features like Dynamic Pipelines.

Labels are made up of a set of additional free-form key-value fields supplied in the configuration YAML. Labels can be a simple set of keys and values, or a more complex nested tree-like structure for more complex use cases.

Labels are stored under a new top-level property in the bitbucket-pipelines.yml file. See the example below.

// simple labels

labels:

&nbsp; my-key: "My value"

  my-other-key: "My other value"

// complex example

labels:

  my-simple-key: "my-simple-value"

&nbsp; my-list:

    - "Item one"

&nbsp; &nbsp; - "Item two"

&nbsp; &nbsp; - "Item three"

  my-nested-object:

    my-nested-key: "My value"

    my-other-nested-key: "My other nested value"

Limitations

We’ve implemented some basic limitations associated with labels to ensure stability and performance. The primary limitation to be aware of is that there is a 10KB size limit to the data stored the labels section. This size is calculated based on the output after the labels section is parsed to JSON, and is roughly equivalent to 200-250 lines of moderately complex JSON.

Exceeding this size limit may lead to builds failing to execute, and an explicit error being shown indicating the labels size limit has been exceeded.

Please let me know if you require further information.

Cheers!

- Ben (Bitbucket Cloud Support)

plussier_hplmja

Hi @Ben,

Thanks, that's helpful. The answers I'm looking for revolve around this snippet that @Edmund Munday showed in this video at 7:06 mark.

labels:
  atlassian:
    managed:
      schemaVersion: 1.0.0
      jvmLibrary:
        buildTool: maven
        mvn: jdk17

Based on what you mentioned above, this labels: block is entirely arbitrary, and up to my own imagination for how to leverage it. But based on Edmund's demo, there seems to be an implied namespace of atlassian which exists. But I can't tell from the demo or what limited documentation I've seen (yours above, and in the dynamic pipelines docs here, whether that namespace is purely an internal Atlassian namespace, or if it's intended to contain a certain schema created by Atlassian for public consumption.

Additionally, I can't find any mention of how to actually parse this block from within my own dynamica pipline code. The only real object discussed for dynamic pipelines seems to be the request.pipelines_configuration object. So I access the labels: block at request.labels for example?

Thanks again for all your help!

Paul

Daniil Penkin

Here's is a shortened version of the clarifications from the support ticket mentioned above to ensure this question remains useful for anyone coming across it later:

Labels are officially supported. The documentation could be better indeed, we plan to improve it in the future.
There's a 10 KB limit on the total size of labels map serialised into JSON. Besides that, there are top-level label namespaces reserved for future and/or internal use, namely atlassian, as of now. This list might be extended in the future, but we'll do our best to make such changes unnoticeable.
- The snippet from the webinar video mentioned above is just an example of labels map used by an internal Dynamic Pipelines provider used within Atlassian.
What's most important about labels map is that it is passed to the Dynamic Pipelines provider as is, and the provider can leverage labels to its advantage. Again, sadly there are no sample scenarios for this in our documentation just yet, and we will consider adding them.
Finally, parsing labels logic depends on the provider implementation:
- Simple Forge function takes in a request object, and labels will be under its pipelines_configuration property, so request.pipelines_configuration.labels would be the way to access labels.
- In case of Forge Remote app, the backend can use any language or framework, and label parsing from the POST payload would rely on whatever tools that stack provides.

Cheers,
Daniil

plussier_hplmja

Hi @Daniil Penkin

Thanks so much for your response! It's great to hear that labels are indeed officially supported!

> The documentation could be better indeed, we plan to improve it in the future.

Improved documentation would be quite welcome. Maybe I'm slower than the average person at picking this stuff up, as I'm not really a developer, and I'm trying to learn both Dynamic Pipelines and TypeScript (also entirely new to me) at the same time. It's certainly been a struggle, but I'm slowly getting there!

> there are top-level label namespaces reserved for future and/or internal use, namely atlassian, as of now

I suspected this based on the video and the mention of the atlassian label. But it was unclear whether the keyword itself was reserved for internal use, or simply the namespace, and by implementing this keyword in our own labels would unlock specific features.

If there is some documentation somewhere which lists what the currently reserved keywords or labels are, that would be great. I would hate to accidentally use any of them, and build up an entire code base around them, only to find out in the future that all my code breaks as a result.

> sadly there are no sample scenarios for this in our documentation just yet, and we will consider adding them.

I think some very robust examples, complete with good comments, unit tests, etc. would be fantastic. There is no better way (for me, at least to learn something than by taking a working example and slowly modifying it for your own needs.

> so request.pipelines_configuration.labels would be the way to access labels

Yes, thank you! I did eventually figure this out on my own, but it's great to have that confirmation!

Thanks again for the response, it's most helpful!

Paul

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

cloud

bitbucket

bitbucket-cloud

bitbucket-pipelines

documentation

dynamic

labels

dynamic-pipelines