Bamboo YAML Specs Tips and Tricks

(For Fun and Profit)

Photo by Jay Wennington on Unsplash

[UPDATED 2021.10.01 WITH ADDITIONAL DEPLOYMENT PLAN LEARNINGS]

[UPDATED 2022.05.14 IN RESPONSE TO A QUESTION IN THE COMMENTS]

Introduction

“In for a penny, in for a pound” — that’s our team’s current approach regarding Atlassian’s products. As part of our efforts to code as much of our infrastructure as possible, we’ve recently begun migrating old build plans to Bamboo Specs and, as non-Java devs who don’t want more headaches than are absolutely necessary, we’ve chosen to work with the Bamboo Specs YAML offering.

YAML specs are pretty great. Migrations are assisted by the fact that manually-created plans will show you their YAML translations, so in most cases a simple copy/paste is all you need. I mean, aside from migrating to linked repositories and ensuring they’re configured correctly…

Having said that, Bamboo’s YAML specs are an incomplete product with undocumented critical features, and fail to provide out-of-the-box support for a surprising number of standard use cases that one would expect software engineers building software for other software engineers to appreciate the value of.
They’re still pretty great in spite of that, but overcoming the limitations of incomplete specs definitions and deployment plans is not particularly intuitive. This article attempts to cover some of the missing pieces and suggest some workarounds that we’ve found useful.

Configuring a linked repository for Bamboo Specs

Bamboo Specs require the configuration of a linked repository. Head to settings -> linked repositories (this will require admin permissions) to create or update a linked repository configuration. The two most important steps to be taken here are as follows:

1. Determine which branch of your repository will be used by Bamboo to read the specs file. Only one branch can be considered the source of truth, my personal recommendation is to make it the development branch.
2. Two sets of permissions need to be configured correctly in order for Bamboo Specs to be able to do their job:
   
   a. First, the Bamboo project must give permissions to the linked…