{"id":30594970,"url":"https://github.com/matthewdeanmartin/bash2gitlab","last_synced_at":"2026-01-20T17:57:35.879Z","repository":{"id":306610925,"uuid":"1022788780","full_name":"matthewdeanmartin/bash2gitlab","owner":"matthewdeanmartin","description":"Compile bash to yaml pipelines to get IDE support for bash and import bash from template repos","archived":false,"fork":false,"pushed_at":"2025-08-24T00:18:27.000Z","size":2726,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-24T07:10:17.609Z","etag":null,"topics":["gitlab","gitlab-ci"],"latest_commit_sha":null,"homepage":"https://bash2gitlab.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matthewdeanmartin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T20:38:04.000Z","updated_at":"2025-08-24T00:18:31.000Z","dependencies_parsed_at":"2025-07-26T20:03:56.860Z","dependency_job_id":"262f6709-51e7-4b20-afe9-33e51871c9a0","html_url":"https://github.com/matthewdeanmartin/bash2gitlab","commit_stats":null,"previous_names":["matthewdeanmartin/bash2gitlab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/matthewdeanmartin/bash2gitlab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewdeanmartin%2Fbash2gitlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewdeanmartin%2Fbash2gitlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewdeanmartin%2Fbash2gitlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewdeanmartin%2Fbash2gitlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matthewdeanmartin","download_url":"https://codeload.github.com/matthewdeanmartin/bash2gitlab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewdeanmartin%2Fbash2gitlab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272758445,"owners_count":24988239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitlab","gitlab-ci"],"created_at":"2025-08-29T20:33:44.785Z","updated_at":"2026-01-20T17:57:35.858Z","avatar_url":"https://github.com/matthewdeanmartin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bash2gitlab\n\n\u003e Compile pure Bash scripts into your `.gitlab-ci.yml`. Get IDE support for your scripts while keeping them\n\u003e centralized.\n\nTired of writing Bash inside YAML strings with no syntax highlighting, linting, or testing? `bash2gitlab` lets you\ndevelop your CI logic in `.sh` files and then compiles them into your GitLab CI configuration, giving you the\nbest of both worlds.\n\nBash in YAML is Bash without quality gates. Also, includes support for inlining a large number of scripts from other\nlanguage, from Python to PHP.\n\n[![tests](https://github.com/matthewdeanmartin/bash2gitlab/actions/workflows/build.yml/badge.svg)\n](https://github.com/matthewdeanmartin/bash2gitlab/actions/workflows/tests.yml)\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/matthewdeanmartin/bash2gitlab/main.svg)\n](https://results.pre-commit.ci/latest/github/matthewdeanmartin/bash2gitlab/main)\n[![Downloads](https://img.shields.io/pypi/dm/bash2gitlab)](https://pypistats.org/packages/bash2gitlab)\n[![Python Version](https://img.shields.io/pypi/pyversions/bash2gitlab)\n![Release](https://img.shields.io/pypi/v/bash2gitlab)\n](https://pypi.org/project/bash2gitlab/)\n\n______________________________________________________________________\n\n## Before\n\nSurely Gitlab has a solution for this? Not as far as I can\ntell. [Here are some of my best workarounds](https://gitlab.com/matthewdeanmartin/includes_templates).\n\nYour IDE sees a single YAML string, and your scripts are trapped in one file.\n\n`.gitlab-ci.yml`:\n\n```yaml\nbuild-job:\n  script:\n    - echo \"Building project\"\n    - make build\n```\n\n## After\n\nYour IDE provides full support for Bash, and your scripts can be versioned, shared, and tested independently.\n\n`scripts/build.sh`:\n\n```bash\n#!/usr/bin/env bash\nset -eo pipefail\n\necho \"Building project\"\nmake build\n```\n\n`uncompiled.gitlab-ci.yml`:\n\n```yaml\nbuild-job:\n  script:\n    - ./scripts/build.sh\n```\n\nRun `bash2gitlab compile`, and the final, valid `.gitlab-ci.yml` is generated for you.\n\n______________________________________________________________________\n\n## Who is this for?\n\nThis tool is for you if:\n\n- You manage CI/CD templates in a centralized repository and `include:` them in many other projects.\n- Your `.gitlab-ci.yml` files contain thousands of lines of shell scripts.\n- You want to write, test, and debug your CI scripts locally without involving Docker or a full pipeline simulation.\n- Your IDE's lack of Bash support in YAML files is slowing you down.\n- You want to be able to put Python or other non-Bash scripts into your shared templates.\n\nIf your CI/CD configuration is simple or contained entirely within a single repository, you might not need this tool.\n\n## Installation\n\n`bash2gitlab` is a standalone command-line tool. Installation with `pipx` is recommended to avoid dependency conflicts.\n\nInstall `[all]` extras for all commands. On your build server install just `bash2gitlab` for the core libraries which\nallows you to run `compile`, `decompile` on server. This minimizes supply chain risks.\n\n```bash\n# Recommended\npipx install bash2gitlab[all]\n\n# Or via pip\npip install bash2gitlab[all]\n```\n\n## Getting Started: A Quick Tour\n\n1. **Initialize Your Project**\n   Run `bash2gitlab init` to create a configuration file (`.bash2gitlab.toml`) and directories to organize your source\n   files.\n\n1. **Decompile an Existing Configuration**\n   If you have an existing `.gitlab-ci.yml` with inline scripts, you can extract them automatically:\n\n```bash\nbash2gitlab decompile --in .gitlab-ci.yml --out my-project/\n```\n\n3. **Write and Edit Your Scripts**\n   Create or edit your `.sh` files in the `scripts` directory. Write standard, clean Bash—your IDE will thank you. In\n   your source YAML (`uncompiled.yml`):\n\n```yaml\nmy-job:\n  script:\n    - ./scripts/my-script.sh\n```\n\n4. **Compile**\n   Compile your source YAML and scripts into a final, GitLab-ready configuration:\n\n```bash\nbash2gitlab compile --in my-project/ --out compiled/\n```\n\nThis generates a `compiled/.gitlab-ci.yml` file, ready to be deployed to your project's root.\n\n## Usage and Commands\n\n`bash2gitlab` provides a few core commands to manage your workflow.\n\nRun with\n\n- bash2gitlab for CLI\n- bash2gitlab-interactive for CLI question and answer\n- bash2gitlab-tui for Terminal UI\n- bash2gitlab-gui for GUI\n\n### Core Compile/Decompile\n\n| Command     | Description                                                                |\n|:------------|:---------------------------------------------------------------------------|\n| `compile`   | Compiles source YAML and `.sh` files into a final `.gitlab-ci.yml`.        |\n| `decompile` | Extracts inline scripts from a `.gitlab-ci.yml` into separate `.sh` files. |\n\n### Debugging from remote repo\n\n| Command      | Description                                                                    |\n|:-------------|:-------------------------------------------------------------------------------|\n| `copy2local` | Copies compiled files from a central repo to a local project for testing.      |\n| `map-deploy` | Copies compiled files from a central repo to a many local project for testing. |\n| `commit-map` | Copies intential changes in local projects back to the central repo.           |\n\n### Setup\n\n| Command               | Description                                              |\n|:----------------------|:---------------------------------------------------------|\n| `init`                | Initializes a new `bash2gitlab` project and config file. |\n| `clean`               | Carefully delete output in target folder.                |\n| `install-precommit`   | Add git hook to compile before commit                    |\n| `uninstall-precommit` | Remove precommit hook                                    |\n\n### Diagnostics\n\n| Command             | Description                                                      |\n|:--------------------|:-----------------------------------------------------------------|\n| `lint`              | Call gitlab APIs to lint your yaml                               |\n| `detect-drift`      | Report what unexpected changes were made to the generated files. |\n| `show-config`       | Display config after cascade                                     |\n| `doctor`            | Look for environment problems                                    |\n| `graph`             | Generate graph of inline relationships                           |\n| `detect-uncompiled` | Detect if you forgot to compile                                  |\n| `validate`          | Validate json schema of all yaml in input and output             |\n\n### Simulate Gitlab Pipeline Locally\n\n| Command | Description                                                                         |\n|:--------|:------------------------------------------------------------------------------------|\n| `run`   | Best efforts to run bash in a .gitlab-ci.yml file in similar order as a real runner |\n\nFor detailed options on any command, run `bash2gitlab \u003ccommand\u003e --help`.\n\n______________________________________________________________________\n\n## Advanced Topics\n\n#### Bash Completion\n\nEnable tab completion in your shell by running the global activation command once:\n\n```bash\nactivate-global-python-argcomplete\n```\n\n#### Global Variables\n\nTo define variables that should be inlined into the global `variables:` block of your `.gitlab-ci.yml`, create a\n`global_variables.sh` file in your input directory.\n\n#### Limitations\n\n- **No `include:` Inlining:** This tool only inlines `.sh` file references. It does not process or merge GitLab's\n  `include:` statements for other YAML files.\n- **Single Statement Invocations:** The script invocation must be on its own line. Multi-statement lines like\n  `echo \"hello\" \u0026\u0026 script.sh` are not supported.\n- **Comments:** Comments in the source YAML may not be preserved in the final compiled output.\n\n## How It Compares\n\n- **[gitlab-ci-local](https://github.com/firecow/gitlab-ci-local):** This is an excellent tool for running your entire\n  GitLab pipeline in local Docker containers. `bash2gitlab` is different—it focuses on the \"unit testing\" of your Bash\n  logic itself, assuming you can and want to execute your scripts on your local machine without the overhead of Docker.\n- **GitHub Actions** [GitHub composite actions](https://docs.github.com/en/actions/concepts/workflows-and-actions/reusable-workflows)\n  do not have this problem. A shared GitHub action can reference a script in the shared action's repo. A GitHub\n  \"reusable\" workflow is a single yaml file and might suffer from the same problem as Gitlab pipelines.\n- **Git Submodules** Build runners will need permissions to clone and git is more complicated to use.\n- **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\n  use other base images.\n- **Trigger remote pipeline** A remote pipeline has access to the shell files in its own repo.\n\n\n## Project Health \u0026 Info\n\n| Metric            | Health                                                                                                                                                                                                              | Metric          | Info                                                                                                                                                                                                              |\n|:------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Tests             | [![Tests](https://github.com/matthewdeanmartin/bash2gitlab/actions/workflows/build.yml/badge.svg)](https://github.com/matthewdeanmartin/bash2gitlab/actions/workflows/build.yml)                                  | License         | [![License](https://img.shields.io/github/license/matthewdeanmartin/bash2gitlab)](https://github.com/matthewdeanmartin/bash2gitlab/blob/main/LICENSE.md)                                                        |\n| Coverage          | [![Codecov](https://codecov.io/gh/matthewdeanmartin/bash2gitlab/branch/main/graph/badge.svg)](https://codecov.io/gh/matthewdeanmartin/bash2gitlab)                                                                | PyPI            | [![PyPI](https://img.shields.io/pypi/v/bash2gitlab)](https://pypi.org/project/bash2gitlab/)                                                                                                                     |\n| Lint / Pre-commit | [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/matthewdeanmartin/bash2gitlab/main.svg)](https://results.pre-commit.ci/latest/github/matthewdeanmartin/bash2gitlab/main)                      | Python Versions | [![Python Version](https://img.shields.io/pypi/pyversions/bash2gitlab)](https://pypi.org/project/bash2gitlab/)                                                                                                  |\n| Quality Gate      | [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=matthewdeanmartin_bash2gitlab\\\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=matthewdeanmartin_bash2gitlab)    | Docs            | [![Docs](https://readthedocs.org/projects/bash2gitlab/badge/?version=latest)](https://bash2gitlab.readthedocs.io/en/latest/)                                                                                    |\n| CI Build          | [![Build](https://github.com/matthewdeanmartin/bash2gitlab/actions/workflows/build.yml/badge.svg)](https://github.com/matthewdeanmartin/bash2gitlab/actions/workflows/build.yml)                                  | Downloads       | [![Downloads](https://static.pepy.tech/personalized-badge/bash2gitlab?period=total\\\u0026units=international_system\\\u0026left_color=grey\\\u0026right_color=blue\\\u0026left_text=Downloads)](https://pepy.tech/project/bash2gitlab) |\n| Maintainability   | [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=matthewdeanmartin_bash2gitlab\\\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=matthewdeanmartin_bash2gitlab) | Last Commit     | ![Last Commit](https://img.shields.io/github/last-commit/matthewdeanmartin/bash2gitlab)                                                                                                                          |\n\n| Category          | Health                                                                                                                                              \n|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Open Issues**   | ![GitHub issues](https://img.shields.io/github/issues/matthewdeanmartin/bash2gitlab)                                                               |\n| **Stars**         | ![GitHub Repo stars](https://img.shields.io/github/stars/matthewdeanmartin/bash2gitlab?style=social)                                               |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewdeanmartin%2Fbash2gitlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatthewdeanmartin%2Fbash2gitlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewdeanmartin%2Fbash2gitlab/lists"}