Bitbucket Pipeline Labels

[plussier]

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

[Daniil Penkin · Accepted solution]

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]

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

[Ben · Accepted solution]

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]

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:

  my-key: "My value"

  my-other-key: "My other value"

// complex example

labels:

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

  my-list:

    - "Item one"

    - "Item two"

    - "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]

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

[Ben]

Hi @plussier 

My sincere apologies for the delay - I'm still waiting for answers from our PM team on this.

To ensure that you are not missed - I've raised a ticket on your behalf in our support portal and have escalated it internally to our engineering team for visibility.

Please check your inbox for further updates, and thank you for your patience thus far.

Cheers!

- Ben (Bitbucket Cloud Support)

[plussier]

Hi @Ben

Thanks so much, and no worries at all! I've been playing around with the example apps and slowly figuring things out.  I'm entirely new to TypeScript, so it's been super slow going, but I'm getting there!

Thanks for raising the ticket, and I see that @Daniil Penkin has also provided an updated answer as well.

Thanks again!

--

Paul

[plussier]

Linking support ticket here for others who stumble across this thread:

[Ben]

Hi @plussier 

Unfortunately, external users can't access that ticket - so I've removed the link. I've asked that our documentation be updated :)

Cheers!

- Ben (Bitbucket Cloud Support)

[plussier]

Hi @Ben 

Thanks. The point was more for people like me. Though I did so assuming the Community members could access the ticket. If not, then, you're right, there's no point :)

Thanks again for all your help!

--

Paul