| Name | bitrab JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Compile bash to gitlab pipeline yaml |
| upload_time | 2025-09-07 22:21:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
bash
gitlab
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Bitrab 🐰
**Local GitLab Compatible CI Runner** - Execute GitLab(TM) CI pipelines locally without Docker
Bitrab is a lightweight, Python-based tool that allows you to run GitLab CI pipelines on your local machine. Perfect for
testing CI configurations, debugging pipeline issues, and rapid development iteration.
Doesn't even require GitLab, works on any build host with python, e.g. GitHub, AWS CodeBuild, anything
GITLAB is a trademark of GitLab Inc. in the United States and other countries and regions. This tool is not affiliated,
endorsed, sponsored, or approved with or by GitLab Inc.
## ✨ Features
- 🚀 **Native execution** - Run pipelines directly on your system (no Docker required)
- 🔄 **Parallel job execution** - Run jobs within stages in parallel for faster execution
- 🎯 **Selective job running** - Execute specific jobs or stages
- 🔍 **Pipeline validation** - Validate your `.gitlab-ci.yml` configuration
- 📊 **Job listing** - View all jobs organized by stages
- 🧪 **Dry-run mode** - Preview what would be executed without running
- ♻️ **Retry logic** - Full GitLab-compatible retry support with backoff strategies
- 🌍 **Variable substitution** - Complete GitLab CI variable support (aspirational feature ATM)
- 📋 **Include directives** - Process `include:` statements like GitLab
- 🎨 **Colored output** - Beautiful terminal output with emoji indicators
## 🚀 Quick Start
### Installation
```bash
pipx install bitrab
```
### Basic Usage
```bash
# Run your .gitlab-ci.yml
bitrab run
# List all jobs in the pipeline
bitrab list
# Validate configuration
bitrab validate
# Run with dry-run to see what would execute
bitrab run --dry-run
# Run with specific parallelism
bitrab run --parallel 4
```
## 📖 Usage
### Commands
#### `bitrab run` (default)
Execute the GitLab CI pipeline locally.
```bash
bitrab run # Run .gitlab-ci.yml
bitrab run -c custom-ci.yml # Use custom config file
bitrab run --dry-run # Preview execution
bitrab run --parallel 2 # Use 2 parallel workers per stage
bitrab run --jobs build test # Run specific jobs (planned)
```
**Options:**
- `--dry-run` - Show commands without executing them
- `--parallel, -j N` - Number of parallel jobs per stage
- `--jobs JOB...` - Run only specified jobs (coming soon)
#### `bitrab list`
Display all jobs organized by stages.
```bash
bitrab list # Show all jobs
bitrab list -c custom-ci.yml # List jobs from custom config
```
#### `bitrab validate`
Validate pipeline configuration and check for common issues.
```bash
bitrab validate # Basic validation
bitrab validate --json # Output validated config as JSON
```
#### `bitrab lint`
Server-side validation using GitLab's official linter (planned).
```bash
bitrab lint # Validate against GitLab API
```
### Global Options
- `-c, --config PATH` - Path to GitLab CI config file (default: `.gitlab-ci.yml`)
- `-q, --quiet` - Suppress non-error output
- `-v, --verbose` - Enable verbose logging
- `--version` - Show version information
- `--license` - Display license information
## 📝 Configuration
Bitrab supports standard GitLab CI YAML configuration:
```yaml
# .gitlab-ci.yml
stages:
- build
- test
- deploy
variables:
NODE_VERSION: "18"
default:
before_script:
- echo "Setting up environment..."
build_job:
stage: build
script:
- echo "Building application..."
- npm install
- npm run build
retry:
max: 2
when: [ script_failure ]
test_job:
stage: test
script:
- echo "Running tests..."
- npm test
variables:
TEST_ENV: "local"
deploy_job:
stage: deploy
script:
- echo "Deploying application..."
only:
- main # Note: 'only' rules are parsed but not enforced locally, not yet
```
### Supported Features
✅ **Fully Supported:**
- `stages` - Pipeline stage definitions
- `variables` - Global and job-level variables
- `default` - Default configuration for all jobs
- `script`, `before_script`, `after_script` - Job execution scripts
- `include` - Include external YAML files
- `retry` - Retry logic with `max`, `when`, and `exit_codes`
- Variable substitution (`$VAR` and `${VAR}`)
⚠️ **Parsed but Limited:**
- `only`, `except`, `rules` - Parsed but not enforced (all jobs run)
- `image`, `services` - Parsed but ignored (no Docker support)
- `cache`, `artifacts` - Parsed but not implemented
❌ **Not Supported:**
- Docker/container execution
- GitLab Runner specific features
- Remote includes (only local file includes)
## 🔧 Advanced Usage
### Environment Variables
Control bitrab behavior with environment variables:
```bash
# Retry configuration
export BITRAB_RETRY_DELAY_SECONDS=3 # Base delay between retries
export BITRAB_RETRY_STRATEGY=exponential # or "constant"
export BITRAB_RETRY_NO_SLEEP=1 # Skip sleep delays
# Subprocess behavior
export BITRAB_SUBPROC_MODE=capture # or "stream"
export NO_COLOR=1 # Disable colored output
```
### Configuration Examples
#### Simple Pipeline
```yaml
# .gitlab-ci.yml
script:
- echo "Hello, Bitrab!"
```
#### Multi-stage Pipeline
```yaml
stages:
- prepare
- build
- test
prepare_env:
stage: prepare
script:
- echo "Preparing environment..."
build_app:
stage: build
script:
- echo "Building application..."
needs: [ prepare_env ]
test_app:
stage: test
script:
- echo "Running tests..."
needs: [ build_app ]
```
#### With Includes
```yaml
# .gitlab-ci.yml
include:
- local: 'ci/build-jobs.yml'
- local: 'ci/test-jobs.yml'
variables:
GLOBAL_VAR: "shared_value"
```
## 🏗️ Architecture
Bitrab consists of several key components:
- **ConfigurationLoader** - Loads and processes YAML configuration with includes
- **PipelineProcessor** - Converts raw config into structured pipeline objects
- **JobExecutor** - Executes individual jobs with retry logic
- **StageOrchestrator** - Manages parallel execution within stages
- **VariableManager** - Handles variable substitution and environment preparation
## 🐛 Troubleshooting
### Common Issues
**Pipeline not found**
```bash
❌ Configuration file not found: .gitlab-ci.yml
```
Make sure you're in a directory with a `.gitlab-ci.yml` file or specify the path with `-c`.
**Job failures**
```bash
❌ Job build_job failed after 1 attempt(s) with exit code 1
```
Check the job script and ensure all commands are valid for your local environment.
**Permission errors**
```bash
❌ Permission denied: ./script.sh
```
Ensure scripts have execute permissions: `chmod +x script.sh`
### Debug Mode
Use the debug command to troubleshoot configuration issues:
```bash
bitrab debug # Show debug information
bitrab validate # Check for configuration errors
bitrab run --dry-run --verbose # Preview with detailed output
```
## 🤝 Contributing
We welcome contributions! Here are some areas where help is needed:
- 🎯 **Job filtering** - Implement selective job execution
- 🔍 **GitLab API integration** - Server-side linting support
- 📊 **Dependency graphs** - Visual pipeline representation
- 🧹 **Artifact management** - Cache and artifact support
- 📈 **Performance profiling** - Execution time analysis
### Development Setup
```bash
git clone https://github.com/your-org/bitrab.git
cd bitrab
pip install -e ".[dev]"
pytest tests/
```
## 📜 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙋 FAQ
**Q: Why not use Docker like GitLab Runner?**
A: Bitrab is designed for local development where you want fast iteration without container overhead. It runs jobs
directly on your system using your existing tools.
**Q: Does it support all GitLab CI features?**
A: Bitrab focuses on core pipeline execution. Features requiring GitLab infrastructure (runners, registry, etc.) are not
supported.
**Q: Can I use this in production?**
A: Bitrab is designed for local development and testing. For production CI/CD, use official GitLab Runners.
**Q: How does retry logic work?**
A: Bitrab implements GitLab-compatible retry with exponential backoff, configurable conditions, and exit code filtering.
---
**Made with ❤️ for developers who love fast local CI/CD iteration**
Raw data
{
"_id": null,
"home_page": null,
"name": "bitrab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bash, gitlab",
"author": null,
"author_email": "Matthew Martin <matthewdeanmartin@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/67/57/285ec4a7be10a34c55e3bc6417169df6f93d34b53c468c7db385474b4663/bitrab-0.1.0.tar.gz",
"platform": null,
"description": "# Bitrab \ud83d\udc30\n\n**Local GitLab Compatible CI Runner** - Execute GitLab(TM) CI pipelines locally without Docker\n\nBitrab is a lightweight, Python-based tool that allows you to run GitLab CI pipelines on your local machine. Perfect for\ntesting CI configurations, debugging pipeline issues, and rapid development iteration.\n\nDoesn't even require GitLab, works on any build host with python, e.g. GitHub, AWS CodeBuild, anything\n\nGITLAB is a trademark of GitLab Inc. in the United States and other countries and regions. This tool is not affiliated,\nendorsed, sponsored, or approved with or by GitLab Inc.\n\n## \u2728 Features\n\n- \ud83d\ude80 **Native execution** - Run pipelines directly on your system (no Docker required)\n- \ud83d\udd04 **Parallel job execution** - Run jobs within stages in parallel for faster execution\n- \ud83c\udfaf **Selective job running** - Execute specific jobs or stages\n- \ud83d\udd0d **Pipeline validation** - Validate your `.gitlab-ci.yml` configuration\n- \ud83d\udcca **Job listing** - View all jobs organized by stages\n- \ud83e\uddea **Dry-run mode** - Preview what would be executed without running\n- \u267b\ufe0f **Retry logic** - Full GitLab-compatible retry support with backoff strategies\n- \ud83c\udf0d **Variable substitution** - Complete GitLab CI variable support (aspirational feature ATM)\n- \ud83d\udccb **Include directives** - Process `include:` statements like GitLab\n- \ud83c\udfa8 **Colored output** - Beautiful terminal output with emoji indicators\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npipx install bitrab\n```\n\n### Basic Usage\n\n```bash\n# Run your .gitlab-ci.yml\nbitrab run\n\n# List all jobs in the pipeline\nbitrab list\n\n# Validate configuration\nbitrab validate\n\n# Run with dry-run to see what would execute\nbitrab run --dry-run\n\n# Run with specific parallelism\nbitrab run --parallel 4\n```\n\n## \ud83d\udcd6 Usage\n\n### Commands\n\n#### `bitrab run` (default)\n\nExecute the GitLab CI pipeline locally.\n\n```bash\nbitrab run # Run .gitlab-ci.yml\nbitrab run -c custom-ci.yml # Use custom config file\nbitrab run --dry-run # Preview execution\nbitrab run --parallel 2 # Use 2 parallel workers per stage\nbitrab run --jobs build test # Run specific jobs (planned)\n```\n\n**Options:**\n\n- `--dry-run` - Show commands without executing them\n- `--parallel, -j N` - Number of parallel jobs per stage\n- `--jobs JOB...` - Run only specified jobs (coming soon)\n\n#### `bitrab list`\n\nDisplay all jobs organized by stages.\n\n```bash\nbitrab list # Show all jobs\nbitrab list -c custom-ci.yml # List jobs from custom config\n```\n\n#### `bitrab validate`\n\nValidate pipeline configuration and check for common issues.\n\n```bash\nbitrab validate # Basic validation\nbitrab validate --json # Output validated config as JSON\n```\n\n#### `bitrab lint`\n\nServer-side validation using GitLab's official linter (planned).\n\n```bash\nbitrab lint # Validate against GitLab API\n```\n\n### Global Options\n\n- `-c, --config PATH` - Path to GitLab CI config file (default: `.gitlab-ci.yml`)\n- `-q, --quiet` - Suppress non-error output\n- `-v, --verbose` - Enable verbose logging\n- `--version` - Show version information\n- `--license` - Display license information\n\n## \ud83d\udcdd Configuration\n\nBitrab supports standard GitLab CI YAML configuration:\n\n```yaml\n# .gitlab-ci.yml\nstages:\n - build\n - test\n - deploy\n\nvariables:\n NODE_VERSION: \"18\"\n\ndefault:\n before_script:\n - echo \"Setting up environment...\"\n\nbuild_job:\n stage: build\n script:\n - echo \"Building application...\"\n - npm install\n - npm run build\n retry:\n max: 2\n when: [ script_failure ]\n\ntest_job:\n stage: test\n script:\n - echo \"Running tests...\"\n - npm test\n variables:\n TEST_ENV: \"local\"\n\ndeploy_job:\n stage: deploy\n script:\n - echo \"Deploying application...\"\n only:\n - main # Note: 'only' rules are parsed but not enforced locally, not yet\n```\n\n### Supported Features\n\n\u2705 **Fully Supported:**\n\n- `stages` - Pipeline stage definitions\n- `variables` - Global and job-level variables\n- `default` - Default configuration for all jobs\n- `script`, `before_script`, `after_script` - Job execution scripts\n- `include` - Include external YAML files\n- `retry` - Retry logic with `max`, `when`, and `exit_codes`\n- Variable substitution (`$VAR` and `${VAR}`)\n\n\u26a0\ufe0f **Parsed but Limited:**\n\n- `only`, `except`, `rules` - Parsed but not enforced (all jobs run)\n- `image`, `services` - Parsed but ignored (no Docker support)\n- `cache`, `artifacts` - Parsed but not implemented\n\n\u274c **Not Supported:**\n\n- Docker/container execution\n- GitLab Runner specific features\n- Remote includes (only local file includes)\n\n## \ud83d\udd27 Advanced Usage\n\n### Environment Variables\n\nControl bitrab behavior with environment variables:\n\n```bash\n# Retry configuration\nexport BITRAB_RETRY_DELAY_SECONDS=3 # Base delay between retries\nexport BITRAB_RETRY_STRATEGY=exponential # or \"constant\"\nexport BITRAB_RETRY_NO_SLEEP=1 # Skip sleep delays\n\n# Subprocess behavior\nexport BITRAB_SUBPROC_MODE=capture # or \"stream\"\nexport NO_COLOR=1 # Disable colored output\n```\n\n### Configuration Examples\n\n#### Simple Pipeline\n\n```yaml\n# .gitlab-ci.yml\nscript:\n - echo \"Hello, Bitrab!\"\n```\n\n#### Multi-stage Pipeline\n\n```yaml\nstages:\n - prepare\n - build\n - test\n\nprepare_env:\n stage: prepare\n script:\n - echo \"Preparing environment...\"\n\nbuild_app:\n stage: build\n script:\n - echo \"Building application...\"\n needs: [ prepare_env ]\n\ntest_app:\n stage: test\n script:\n - echo \"Running tests...\"\n needs: [ build_app ]\n```\n\n#### With Includes\n\n```yaml\n# .gitlab-ci.yml\ninclude:\n - local: 'ci/build-jobs.yml'\n - local: 'ci/test-jobs.yml'\n\nvariables:\n GLOBAL_VAR: \"shared_value\"\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\nBitrab consists of several key components:\n\n- **ConfigurationLoader** - Loads and processes YAML configuration with includes\n- **PipelineProcessor** - Converts raw config into structured pipeline objects\n- **JobExecutor** - Executes individual jobs with retry logic\n- **StageOrchestrator** - Manages parallel execution within stages\n- **VariableManager** - Handles variable substitution and environment preparation\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n**Pipeline not found**\n\n```bash\n\u274c Configuration file not found: .gitlab-ci.yml\n```\n\nMake sure you're in a directory with a `.gitlab-ci.yml` file or specify the path with `-c`.\n\n**Job failures**\n\n```bash\n\u274c Job build_job failed after 1 attempt(s) with exit code 1\n```\n\nCheck the job script and ensure all commands are valid for your local environment.\n\n**Permission errors**\n\n```bash\n\u274c Permission denied: ./script.sh\n```\n\nEnsure scripts have execute permissions: `chmod +x script.sh`\n\n### Debug Mode\n\nUse the debug command to troubleshoot configuration issues:\n\n```bash\nbitrab debug # Show debug information\nbitrab validate # Check for configuration errors\nbitrab run --dry-run --verbose # Preview with detailed output\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here are some areas where help is needed:\n\n- \ud83c\udfaf **Job filtering** - Implement selective job execution\n- \ud83d\udd0d **GitLab API integration** - Server-side linting support\n- \ud83d\udcca **Dependency graphs** - Visual pipeline representation\n- \ud83e\uddf9 **Artifact management** - Cache and artifact support\n- \ud83d\udcc8 **Performance profiling** - Execution time analysis\n\n### Development Setup\n\n```bash\ngit clone https://github.com/your-org/bitrab.git\ncd bitrab\npip install -e \".[dev]\"\npytest tests/\n```\n\n## \ud83d\udcdc License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4b FAQ\n\n**Q: Why not use Docker like GitLab Runner?**\nA: Bitrab is designed for local development where you want fast iteration without container overhead. It runs jobs\ndirectly on your system using your existing tools.\n\n**Q: Does it support all GitLab CI features?**\nA: Bitrab focuses on core pipeline execution. Features requiring GitLab infrastructure (runners, registry, etc.) are not\nsupported.\n\n**Q: Can I use this in production?**\nA: Bitrab is designed for local development and testing. For production CI/CD, use official GitLab Runners.\n\n**Q: How does retry logic work?**\nA: Bitrab implements GitLab-compatible retry with exponential backoff, configurable conditions, and exit code filtering.\n\n---\n\n**Made with \u2764\ufe0f for developers who love fast local CI/CD iteration**",
"bugtrack_url": null,
"license": null,
"summary": "Compile bash to gitlab pipeline yaml",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/matthewdeanmartin/bitrab/blob/main/CHANGELOG.md",
"Documentation": "https://bitrab.readthedocs.io/en/latest/",
"Repository": "https://github.com/matthewdeanmartin/bitrab",
"homepage": "https://github.com/matthewdeanmartin/bitrab",
"issues": "https://github.com/matthewdeanmartin/bitrab/issues/"
},
"split_keywords": [
"bash",
" gitlab"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f26b45070faa7529233251147e386294dbcd5b174ad5c7c2918fef44c9aae667",
"md5": "7a52e3d1e1cdd2c8607dc24ea8ba2a1d",
"sha256": "bbd633a7648d397c9e6ccbcc90d285e53074840c7df20954241034e912f9310d"
},
"downloads": -1,
"filename": "bitrab-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a52e3d1e1cdd2c8607dc24ea8ba2a1d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 48056,
"upload_time": "2025-09-07T22:21:25",
"upload_time_iso_8601": "2025-09-07T22:21:25.118616Z",
"url": "https://files.pythonhosted.org/packages/f2/6b/45070faa7529233251147e386294dbcd5b174ad5c7c2918fef44c9aae667/bitrab-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6757285ec4a7be10a34c55e3bc6417169df6f93d34b53c468c7db385474b4663",
"md5": "1c51af5f76c9394513f0f32ac05bb421",
"sha256": "785ef331f9daed95c8a1847491428008971e5153c769d6ba60a5c64e7735fd62"
},
"downloads": -1,
"filename": "bitrab-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1c51af5f76c9394513f0f32ac05bb421",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 44527,
"upload_time": "2025-09-07T22:21:26",
"upload_time_iso_8601": "2025-09-07T22:21:26.835997Z",
"url": "https://files.pythonhosted.org/packages/67/57/285ec4a7be10a34c55e3bc6417169df6f93d34b53c468c7db385474b4663/bitrab-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 22:21:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matthewdeanmartin",
"github_project": "bitrab",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "bitrab"
}
