Bitrise releases Modular YAML: A game changer for CI/CD configuration management

At Bitrise, our goal is to make configuration management as intuitive, clear, flexible, and efficient as possible. As tech projects scale and complexities grow, managing large YAML configuration files can become a daunting task. Bitrise is excited to introduce the Modular YAML configuration feature, aimed at simplifying how your CI/CD configuration. This new capability allows you to split extensive YAML files into smaller, reusable modules, ensuring easier maintenance, enhanced readability, and efficient reuse across multiple projects.

😓 The challenge with monolithic YAML Files

YAML configuration files serve as the backbone for defining steps, workflows, and pipelines. However, as projects expand, these files often grow into massive, monolithic entities that are cumbersome to manage. Users struggle to:

• Understand the overall configuration.
• Locate the right sections for making changes.
• Define ownership of different parts of the YAML.
• Manage redundant configuration blocks, increasing the risk of errors and merge conflicts.

Moreover, maintaining duplicate configurations across apps can be a time-consuming and error-prone process. This is where Bitrise Modular YAML comes into play.

🦸🏽 Modular YAML to the rescue!

Modular YAML dismantles these challenges by enabling you to break down your bitrise.yml file into smaller, reusable modules. These modules can be easily included in your main configuration using the include syntax.

🤩 Key benefits

💡 Enhanced readability & organization: Breaking down a large YAML file into smaller, logical modules makes it easier to understand the overall configuration. This makes it easier to navigate and manage your configurations, especially for new team members.

😍 Improved maintainability: You can quickly locate specific parts of the configuration, speeding up the process of making changes and reducing errors. Update a configuration in the relevant module without affecting the entire file, making changes easier to test and implement. Additionally, you can reuse common configuration blocks across multiple apps. With Modular YAML, common configurations are centralized, allowing updates to be made in one place and propagated across all relevant projects. More on that below.

🤝 Better ownership and collaboration: You can assign ownership of different parts of the configuration to specific team members, enhancing collaboration and accountability. Multiple team members can work on different parts of the configuration simultaneously, reducing the likelihood of merge conflicts.

🧐 Enhanced error isolation and debugging: This approach also makes it easier to isolate and debug issues within smaller modules, speeding up the resolution process. Update and test smaller parts of the configuration independently, reducing the risk of introducing errors into your CI/CD pipeline.

📈 Scalability: Modular YAML allows Bitrise users to scale their CI/CD configurations with ease. You can add new modules, and update existing ones, all without disrupting your entire setup.

📖 How it works: Introducing the include format

The include feature lets you incorporate external YAML files into your main configuration. Here’s an example:

include:
  - path: file/path/common.yml

It requires one parameter: path, which is the location of the YAML file to be included. The provided path must be relative to the repository’s root. You can include a file from a different repository by specifying the repository name. Check out the documentation here.

include:
  - path: path/common.yml # Required. Relative path from repo root
    branch: feature/cool-feature # Optional. Default: the Bitrise app's default branch on website, empty in local env
    tag: release-1.0.final.v2.final # Optional. Default: empty
    commit: abc12345 # Optional. Default: empty on website and checked out ref in local env 
    repository: bitrise-website # Optional. When set, one of branch/tag/commit is required. Default: same as in Bitrise app's git url and in checked out git repo url in local env

Bitrise’s Modular YAML stands out against competitors like Jenkins, GitHub Actions, Circle CI, and GitLab by offering:

• Simple syntax: Learn only how to use include.
• Better readability: Smaller, well-organized modules improve readability and ease of management.
• Flexible referencing across repositories: Easily include files from the same repository, different branches, tags, commits, or even from other repositories using parameters.
• Granular extraction: Any part of the YAML configuration can be modularized, whether it’s a single step, workflow, or the entire pipeline.

🔍 Some examples of how you could modularize your YAML

1. By Workflow types:
   • Split workflows by their function, such as build, test, deploy, etc.

# Main bitrise.yml:

include:
  - path: workflows/build.yml
  - path: workflows/test.yml
  - path: workflows/deploy.yml

# workflows/build.yml:

workflows:
  build:
    steps:
      - git-clone: {}
      - npm-install: {}
      - xcode-build-for-test: {}

# workflows/deploy.yml:

workflows:
  deploy:
    steps:
      - deploy-to-itunesconnect: {}

2. By Environment:
   • Create separate configurations for different environments like development, staging, production, etc.

# Main bitrise.yml:

include:
  - path: environments/development.yml
  - path: environments/staging.yml
  - path: environments/production.yml

# environments/development.yml:

workflows:
  deploy_dev:
    steps:
      - git-clone: {}
      - npm-install: {}
      - deploy-to-development-server: {}

# environments/staging.yml:

workflows:
  test:
    steps:
      - xcode-test: {}
      - deploy-to-bitrise-io: {}

# environment/production.yml:

workflows:
  deploy:
    steps:
      - deploy-to-itunesconnect: {}

3. By project components:
   • For projects with multiple components (e.g., microservices, frontend, backend), create individual configurations for each component.

# Main bitrise.yml:

include:
  - path: components/backend.yml
  - path: components/frontend.yml
  - path: components/mobile.yml

4. By team responsibility:
   • Organize configurations based on which team or team member is responsible for them.

include:
  - path: teams/alpha-team.yml
  - path: teams/bravo-team.yml

4. By reusable steps or scripts:
   • Extract common steps or scripts used across multiple workflows into separate files.

Best Practices:

• Consistency: Maintain consistent naming conventions and structure across files to ensure clarity.
• Documentation: Document the purpose of each YAML file and what it includes.
• Version control: Keep the modular YAML files under version control to track changes and collaborate effectively.
• Reuse: Aim to reuse common steps and configurations to minimize duplication and simplify updates. Also, consider using “step bundles” . It’ll simplify your config reuse needs.

By following these strategies and examples, you can effectively split your YAML configuration files in a way that enhances maintainability, readability, and

Getting started with Modular YAML

Getting started is fairly easy. Check out the documentation here.

‍