bash2yaml

Requires Python 3.11 or newer.

Compile pure Bash scripts into your CI/CD YAML. Get IDE support for your scripts while keeping them centralized.

Tired of writing Bash inside YAML strings with no syntax highlighting, linting, or testing? bash2yaml lets you develop your CI logic in .sh files and then compiles them into your CI/CD configuration, giving you the best of both worlds.

Supported targets: GitLab CI, GitHub Actions, CircleCI, AWS CodeBuild, Bitbucket Pipelines, and Semaphore CI.

Bash in YAML is Bash without quality gates. Also, includes support for inlining a large number of scripts from other language, from Python to PHP.

Before

Surely Gitlab has a solution for this? Not as far as I can tell. Here are some of my best workarounds.

Your IDE sees a single YAML string, and your scripts are trapped in one file.

.gitlab-ci.yml:

build-job:
  script:
    - echo "Building project"
    - make build

After

Your IDE provides full support for Bash, and your scripts can be versioned, shared, and tested independently.

scripts/build.sh:

#!/usr/bin/env bash
set -eo pipefail

echo "Building project"
make build

uncompiled.gitlab-ci.yml:

build-job:
  script:
    - ./scripts/build.sh

Run bash2yaml compile, and the final, valid .gitlab-ci.yml is generated for you.

Who is this for?

This tool is for you if:

• You manage CI/CD templates in a centralized repository and include: them in many other projects.
• Your .gitlab-ci.yml files contain thousands of lines of shell scripts.
• You want to write, test, and debug your CI scripts locally without involving Docker or a full pipeline simulation.
• Your IDE's lack of Bash support in YAML files is slowing you down.
• You want to be able to put Python or other non-Bash scripts into your shared templates.

If your CI/CD configuration is simple or contained entirely within a single repository, you might not need this tool.

Installation

bash2yaml is a standalone command-line tool. Installation with pipx is recommended to avoid dependency conflicts.

Install [all] for every optional feature, [fast] for native speedups only, or [pure-python-features] for the optional command/UI stack without native extensions. The deprecated [bitrab] extra remains as a compatibility alias. On your build server you can still install plain bash2yaml for the core compile/decompile flow to minimize supply chain risk.

# Recommended
pipx install bash2yaml[all]
pipx install bash2yaml[fast]

# Or via pip
pip install bash2yaml[all]
pip install bash2yaml[pure-python-features]

Getting Started: A Quick Tour

1. Initialize Your Project Run bash2yaml init to create a configuration file (.bash2yaml.toml) and directories to organize your source files.

2. Decompile an Existing Configuration If you have an existing .gitlab-ci.yml with inline scripts, you can extract them automatically:

bash2yaml decompile --in-file .gitlab-ci.yml --out my-project/

3. Write and Edit Your Scripts Create or edit your .sh files in the scripts directory. Write standard, clean Bash—your IDE will thank you. In your source YAML (uncompiled.yml):

my-job:
  script:
    - ./scripts/my-script.sh

4. Compile Compile your source YAML and scripts into a final, GitLab-ready configuration:

bash2yaml compile --in my-project/ --out compiled/

This generates a compiled/.gitlab-ci.yml file, ready to be deployed to your project's root.

Usage and Commands

bash2yaml provides a few core commands to manage your workflow.

Run with

• bash2yaml for CLI
• bash2yaml-interactive for CLI question and answer
• bash2yaml-tui for Terminal UI
• bash2yaml-gui for GUI

Core Compile/Decompile

Debugging from remote repo

Setup

Diagnostics

Other

For detailed options on any command, run bash2yaml <command> --help.

Advanced Topics

Bash Completion

Enable tab completion in your shell by running the global activation command once:

activate-global-python-argcomplete

Global Variables

To define variables that should be inlined into the global variables: block of your .gitlab-ci.yml, create a global_variables.sh file in your input directory.

Limitations

• No include: Inlining: This tool only inlines .sh file references. It does not process or merge GitLab's include: statements for other YAML files.
• Single Statement Invocations: The script invocation must be on its own line. Multi-statement lines like echo "hello" && script.sh are not supported.
• Comments: Comments in the source YAML may not be preserved in the final compiled output.

How It Compares

• gitlab-ci-local: This is an excellent tool for running your entire GitLab pipeline in local Docker containers. bash2yaml is different—it focuses on the "unit testing" of your Bash logic itself, assuming you can and want to execute your scripts on your local machine without the overhead of Docker.
• **GitHub Actions ** GitHub composite actions do not have this problem. A shared GitHub action can reference a script in the shared action's repo. A GitHub "reusable" workflow is a single yaml file and might suffer from the same problem as Gitlab pipelines.
• Git Submodules Build runners will need permissions to clone and git is more complicated to use.
• Base image holds all bash You can only have one base image, so if you are using it for bash and yaml, you can't use other base images.
• Trigger remote pipeline A remote pipeline has access to the shell files in its own repo.

Project Health & Info

Metric	Health	Metric	Info
Tests		License
Coverage		PyPI
Lint / Pre-commit		Python Versions
Quality Gate		Docs
CI Build		Downloads
Maintainability		Last Commit

Category	Health
Open Issues
Stars

Project Links

• GitHub
• PyPI
• Documentation
• Bug Tracker
• Change Log