How to use Bamboo YAML Specs to manage multiple plans and deployments in one repository
Platform Notice: Data Center - This article applies to Atlassian products on the Data Center platform.
Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles for non-Data Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
The steps outlined on this article are provided AS-IS. This means we've had reports of them working for some customers — under certain circumstances — yet are not officially supported, nor can we guarantee they'll work for your specific scenario.
You may follow through and validate them on your own non-prod environments prior to production or fall back to supported alternatives if they don't work out.
We also invite you to reach out to our Community for matters that fall beyond Atlassian's scope of support!
Summary
This article explains how to manage multiple Bamboo plans and deployments within a single repository using Bamboo YAML Specs. It explains how to structure and organize Bamboo Specs files, as well as highlights potential risks associated with this approach.
Environment
The solution was tested on Bamboo 9.6.1, but it will be applicable to other supported versions as well.
Potential Risks
Please be aware of the following risks before considering this solution:
- Any commits made to the Specs repository will trigger a scan of all plans and deployments defined in the repository.
A single commit to a repository can trigger all plans within that repository at once, causing all available agents to become occupied and potentially leading to delays and longer build times.
It can become quite challenging to manage, particularly as the number of plans and deployments increases over time.
Solution
Bamboo YAML Specs were designed as a simpler alternative to Bamboo Java Specs for customers who need configuration-as-code but don't require the full feature set of Java Specs, or who may not have the capability to use Java. YAML Specs are intended to be used on a per-plan, per-repository basis and provide a more streamlined, lightweight approach compared to Java Specs.
The solution below demonstrates how to use the !include keyword to reference multiple YAML files containing plan and deployment configurations. Please note that while bamboo.yaml supports multi-block YAML configurations, the YAML files referenced by the !include tag should not contain multi-block structures. Instead, each included file should have a simple, flat structure to ensure proper compatibility and parsing.
Create separate YAML files for each plan along with its respective permissions, as illustrated in the example folder structure below. This structure is only a suggested approach and can be customized based on your specific requirements.
.
└── bamboo-specs
├── bamboo.yaml
├── builds
│ ├── PlanA-build-plan.yaml
│ ├── PlanA-permission.yaml
│ ├── PlanB-build-plan.yaml
│ ├── PlanB-permission.yaml
│ ├── PlanC-build-plan.yaml
│ └── PlanC-permission.yaml
└── deployments
├── DeployA-deployment-plan.yaml
├── DeployA-permission.yaml
├── DeployB-deployment-plan.yaml
├── DeployB-permission.yaml
├── DeployC-deployment-plan.yaml
└── DeployC-permission.yamlBelow are sample contents for each YAML file.
version: 2
plan:
project-key: SR
key: TPA
name: Test PlanA
stages:
- Default Stage:
manual: false
final: false
jobs:
- Default Job
Default Job:
key: JOB1
tasks:
- checkout:
force-clean-build: false
- script:
interpreter: SHELL
scripts:
- echo PlanAversion: 2
plan:
key: SR-TPA
plan-permissions:
- roles:
- logged-in
- anonymous
permissions:
- viewversion: 2
deployment:
name: Test DeployA
source-plan: SR-TPA
release-naming:
next-version-name: release-1
applies-to-branches: false
auto-increment: true
auto-increment-variables: []
environments:
- ENV1
ENV1:
triggers: []
tasks:
- clean
- artifact-download:
artifacts:
- {}
description: Download release contents
- script:
interpreter: SHELL
scripts:
- echo 'DeployA'version: 2
deployment:
name: Test DeployA
deployment-permissions:
- roles:
- logged-in
- anonymous
permissions:
- viewOnce all the build and deployment YAML files are created, include them in the
bamboo.yamlfile using the!includetag as shown below.
---
!include builds/PlanA-build-plan.yaml
---
!include builds/PlanA-permission.yaml
---
!include builds/PlanB-build-plan.yaml
---
!include builds/PlanB-permission.yaml
---
!include builds/PlanC-build-plan.yaml
---
!include builds/PlanC-permission.yaml
---
!include deployments/DeployA-deployment-plan.yaml
---
!include deployments/DeployA-permission.yaml
---
!include deployments/DeployB-deployment-plan.yaml
---
!include deployments/DeployB-permission.yaml
---
!include deployments/DeployC-deployment-plan.yaml
---
!include deployments/DeployC-permission.yamlIf the plan configurations need to be further split into multiple YAML files for each job and stage, particularly when the configuration needs to be reused, please refer to the following knowledge base article: Bamboo YAML Specs - Unable to Parse the !include Tag at Stage Level.
If both plan configurations and permissions are included in the same YAML file, and that file is referenced using the !include tag, it may lead to the issue outlined in the bug BAM-21510 - YAML Spec scan fails if the include tag files contains permission definition. Please ensure that plan configurations and permissions are kept in separate files.