Bamboo YAML specs unable to parse the "!include" tag at stage level
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
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
Summary
When publishing a Bamboo YAML Specs plan that contains an !include tag at the stage or job level, the publishing process may fail, and the following error is typically observed:
Bamboo YAML import failed: Invalid format of the YAML file: expected a single document in the streamEnvironment
Any supported version of Bamboo (observed in Bamboo 8.0.3).
Diagnosis
When creating a YAML project to publish a plan in Bamboo, you might do a breakdown of the script into multiple files and use "!include" tags to correlate them.
YAML requires precision when it comes to parsing. If a parsing mistake is made while using "!include" tasks, then the error mentioned above will be shown.
This is an example of a YAML file with a parsing error:
---
!include 'build/plan-Stage1.yml'
---
!include 'build/plan-Stage2.yml'The build/publish error will show the following information:
08-Feb-2022 17:06:41 Bamboo YAML import failed: Invalid format of the YAML file: expected a single document in the stream
08-Feb-2022 17:06:41 in 'reader', line 2, column 1:
08-Feb-2022 17:06:41 !include 'build/plan-Stage1.yml
08-Feb-2022 17:06:41 ^
08-Feb-2022 17:06:41 but found another documentCause
In order to use an "!include" tag at a stage level, it must be appended onto another tag. It must also follow the indentation rules needed in YAML files. The publishing fails due to invalid file formatting.
Solution
Create separate YAML files for Plan, Stage and Job, 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
├── app1
│ └── svc1
│ ├── planA
│ │ ├── job.yaml
│ │ ├── plan.yaml
│ │ └── stages.yaml
│ └── planB
│ ├── job.yaml
│ ├── plan.yaml
│ └── stages.yaml
├── app2
│ └── svc2
│ ├── planC
│ │ ├── job.yaml
│ │ ├── plan.yaml
│ │ └── stages.yaml
│ └── planD
│ ├── job.yaml
│ ├── plan.yaml
│ └── stages.yaml
└── bamboo.yaml- In
bamboo.yaml, append the!includetag to other tags as shown below. This way, the YAML engine can append and parse both parent and child YAML files together.
---
version: 2
plan: !include 'app1/svc1/planA/plan.yaml'
stages: !include 'app1/svc1/planA/stages.yaml'
Default Job: !include 'app1/svc1/planA/job.yaml'
---
version: 2
plan: !include 'app1/svc1/planB/plan.yaml'
stages: !include 'app1/svc1/planB/stages.yaml'
Default Job: !include 'app1/svc1/planB/job.yaml'
---
version: 2
plan: !include 'app2/svc2/planC/plan.yaml'
stages: !include 'app2/svc2/planC/stages.yaml'
Default Job: !include 'app2/svc2/planC/job.yaml'
---
version: 2
plan: !include 'app2/svc2/planD/plan.yaml'
stages: !include 'app2/svc2/planD/stages.yaml'
Default Job: !include 'app2/svc2/planD/job.yaml'- Below are sample contents for each YAML file
project-key: TP
key: TPA
name: Test PlanA- Default Stage:
manual: false
final: false
jobs:
- Default Job key: JOB1
tasks:
- script:
interpreter: SHELL
scripts:
- echo app1/svc1/planAIf the entire plan configuration can be defined in a single YAML file, instead of splitting stages and jobs across multiple files, a much simpler approach can be used. For detailed instructions, please refer to the following knowledge base article: How to Use Bamboo YAML Specs to Manage Multiple Plans and Deployments in One Repository.
Currently, Bamboo does not support nested sequencing in the YAML file to include multiple !include statements without specifying tag names. However, there is an open suggestion BAM-20497 - Allow nested sequences of tasks to work in YAML Specs for this feature to address the requirement in future releases.