GitBoiler 🚀

CLI to manage GitLab environment variables in an intuitive and efficient way.

Features

• 🔧 Complete GitLab environment variables management
• 📁 Synchronization with local .env files
• 🎯 Support for multiple environments (develop, production, etc.)
• 📊 Diff visualization before applying changes
• 🔒 Support for protected and masked variables
• ⚡ Intuitive command-line interface
• 🚀 Powered by GitBeaker for robust GitLab API integration

Installation

# Install dependencies and make globally executable
pnpm run setup

# Or manually:
pnpm install
pnpm link --global

Initial Setup

Manual Configuration

Before using GitBoiler, you need to configure it:

gitboiler init

You will be prompted to provide:

• GitLab URL (e.g., https://gitlab.com)
• GitLab access token
• Project ID

How to get GitLab Access Token

1. Go to your GitLab instance
2. Navigate to Settings > Access Tokens
3. Create a new token with api scope
4. Copy the generated token

How to get Project ID

1. Go to your project in GitLab
2. The ID appears right below the project name on the main page

Usage

List Variables

# List all variables
gitboiler list

# List variables from specific environment
gitboiler list -e production

Set Variable

# Set variable in develop environment (default)
gitboiler set DATABASE_URL "postgresql://localhost:5432/mydb"

# Set variable in specific environment
gitboiler set API_KEY "secret123" -e production

# Set protected and masked variable
gitboiler set SECRET_TOKEN "ultra-secret" -e production --protected --masked

Delete Variable

# Delete variable from develop environment
gitboiler delete OLD_CONFIG

# Delete variable from specific environment
gitboiler delete TEMP_KEY -e staging

Push Local Variables to GitLab

# Push .env.develop file to GitLab
gitboiler push -e develop

# Push specific file
gitboiler push -e production -f .env.prod

# Preview changes without applying (dry-run)
gitboiler push -e develop --dry-run

# Push with protection flags for new variables
gitboiler push -e production --protected --masked

Pull GitLab Variables to Local

# Pull GitLab variables to .env.develop
gitboiler pull -e develop

# Pull to specific file
gitboiler pull -e production -f .env.prod

# Preview what would be pulled (dry-run)
gitboiler pull -e develop --dry-run

# Merge with existing local variables (preserve local)
gitboiler pull -e develop --merge

Sync with .env File

# Sync .env.develop file with GitLab (bidirectional - removes GitLab-only vars)
gitboiler sync -e develop

# Sync with merge mode (preserves GitLab-only variables)
gitboiler sync -e develop --merge

# Sync specific file
gitboiler sync -e production -f .env.prod

# Preview changes without applying (dry-run)
gitboiler sync -e develop --dry-run

Compare Differences

# Show differences between local and GitLab
gitboiler diff -e develop

# Compare specific file
gitboiler diff -e production -f .env.prod

.env File Structure

GitBoiler follows standard .env file conventions:

# .env.develop
DATABASE_URL=postgresql://localhost:5432/dev_db
API_KEY=dev_api_key
DEBUG=true

# .env.production  
DATABASE_URL=postgresql://prod-server:5432/prod_db
API_KEY=prod_api_key
DEBUG=false

Commands Comparison

Push vs Pull vs Sync vs Diff

• push - One-way: Local .env → GitLab (only updates GitLab with local changes)
• pull - One-way: GitLab → Local .env (downloads GitLab variables to local file)
• sync - Two-way: Local .env ↔ GitLab (synchronizes both, removes extra variables)
• diff - Read-only: Shows differences without making changes

When to use each:

• Use push when you want to deploy local changes to GitLab
• Use pull when you want to download GitLab variables to your local environment
• Use sync when you want complete synchronization (local and GitLab become identical)
• Use diff to preview what would change before running push, pull, or sync

Pull modes:

• Replace mode (default): Overwrites local file with GitLab variables
• Merge mode (--merge): Preserves local variables and adds/updates from GitLab

Environment Scopes

GitBoiler supports all GitLab environment scopes:

Standard Environments

• develop, staging, production - Specific environments
• Custom environment names (e.g., qa, testing, demo)

Global Environment (*)

The special environment * (asterisk) applies to all branches/environments:

# Set a global variable (applies to all environments)
gitboiler set GLOBAL_CONFIG "value" -e "*"

# List global variables
gitboiler list -e "*"

# Pull global variables to .env (without suffix)
gitboiler pull -e "*"

Usage notes:

• Environment * uses .env file (no suffix)
• Aliases: all, global also map to *
• Global variables have lower priority than environment-specific ones

Special Characters

GitLab has limitations with some characters in variable names. GitBoiler automatically converts:

• / → [slash]
• * → [star]

Example:

• PATH/TO/FILE → PATH[slash]TO[slash]FILE in GitLab
• WILDCARD*PATTERN → WILDCARD[star]PATTERN in GitLab

Usage Examples

Typical Workflow

1. Initialize configuration:

   gitboiler init
   # Follow the prompts to enter your GitLab URL, token, and project ID

2. Create environment file:

   # Create .env.develop with your variables
   echo "DATABASE_URL=postgres://localhost/myapp_dev" > .env.develop
   echo "API_KEY=your-dev-api-key" >> .env.develop

3. Preview differences:

   gitboiler diff -e develop

4. Push to GitLab:

   gitboiler push -e develop

5. Verify in GitLab:

   gitboiler list -e develop

Alternative: Start from GitLab

If you already have variables in GitLab and want to pull them locally:

1. Initialize configuration:

   gitboiler init
   # Follow the prompts to enter your GitLab URL, token, and project ID

2. Pull variables from GitLab:

   gitboiler pull -e develop

3. Review and update the generated .env file:

   # Check the .env.develop file and update masked values

Managing Multiple Environments

# Global variables (all environments)
gitboiler push -e "*"

# Development
gitboiler push -e develop -f .env.develop

# Staging
gitboiler push -e staging -f .env.staging  

# Production
gitboiler push -e production -f .env.production

Working with Global Variables

# Set global variables that apply everywhere
gitboiler set COMPANY_NAME "My Company" -e "*"
gitboiler set SUPPORT_EMAIL "[email protected]" -e "*"

# Pull global variables
gitboiler pull -e "*"    # Creates/updates .env

# List all variables grouped by environment
gitboiler list           # Shows: * (Global/All branches), develop, production, etc.

Available Commands

| Command | Description | Options | |---------|-------------|--------| | init | Configure GitLab connection | - | | list | List variables | -e environment | | set <key> <value> | Set variable | -e environment, --protected, --masked | | delete <key> | Delete variable | -e environment | | push | Push local .env to GitLab | -e environment, -f file, --dry-run, --protected, --masked | | pull | Pull GitLab variables to local .env | -e environment, -f file, --dry-run, --merge | | sync | Sync with .env file (bidirectional) | -e environment, -f file, --dry-run | | diff | Show differences | -e environment, -f file |

Configuration Files

• .gitboiler.json - GitLab connection configuration (don't commit!)
• .env.* - Environment variable files per environment

Development

Testing

GitBoiler uses Node.js 24.11.1+ native test runner. No external test frameworks required.

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage (experimental)
pnpm test:coverage

All tests include mocks for GitLab API calls. See docs/testing.md for detailed testing documentation.

Test Coverage:

• ✅ 59 tests across 14 suites
• ✅ 100% coverage of core functionality
• ✅ GitLab API mocked (no real API calls)
• ✅ Edge cases and error handling

Code Quality

# Format code
pnpm run format

# Lint code
pnpm run lint

# Check everything
pnpm run check

Security

⚠️ Important:

• Add .gitboiler.json to your .gitignore
• Never commit access tokens
• Use masked variables for sensitive data
• Use protected variables to avoid exposure in logs

Contributing

Contributions are welcome! Feel free to open issues and pull requests.

License

ISC