Solarboat CLI 🚀

Built with love for Rust and infrastructure automation by Youssef Hussein (@devqik)

Solarboat is a modern CLI for Infrastructure as Code (IaC) and GitOps workflows, providing intelligent Terraform operations, automatic dependency detection, and seamless stateful/stateless module handling.

<img src="./solarboat.png" alt="Solarboat Logo" width="100%">

---

✨ Features

• Intelligent Terraform Operations
  • Detects changed modules automatically
  • Handles stateful/stateless modules smartly
  • Propagates dependencies
  • Runs modules in parallel (with safety limits)
  • Detailed, readable reporting
  • Path-based filtering for targeted runs
• Coming Soon
  • AI agent
  • Automatic state management
  • Custom workflow automation

---

📦 Installation

With Cargo (Recommended):

cargo install solarboat
# Or install a specific version
cargo install solarboat --version 0.8.9

From Release Binaries:

curl -L https://github.com/devqik/solarboat/releases/latest/download/solarboat-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv solarboat /usr/local/bin/

From Source:

git clone https://github.com/devqik/solarboat.git
cd solarboat
cargo build

---

🛠️ Usage

Common Commands

# Scan for changed Terraform modules
solarboat scan

# Scan a specific directory
solarboat scan --path ./terraform-modules

# Scan with custom default branch
solarboat scan --default-branch develop

# Plan Terraform changes
solarboat plan

# Plan in parallel
solarboat plan --parallel 4

# Save plans to directory
solarboat plan --output-dir ./terraform-plans

# Ignore workspaces
solarboat plan --ignore-workspaces dev,staging

# Plan all stateful modules
solarboat plan --all

# Apply changes (dry-run by default)
solarboat apply

# Apply for real
solarboat apply --dry-run=false

# Ignore workspaces
solarboat apply --ignore-workspaces prod,staging

# Apply all stateful modules
solarboat apply --all

# Real-time output
solarboat plan --watch

# Combine flags
solarboat plan --all --watch --var-files vars.tfvars

Command Overview

• scan: Analyze repo for changed modules and dependencies. No changes made.
• plan: Generate Terraform plans for changed modules. Supports parallelism, workspace filtering, and output directory.
• apply: Apply changes to infrastructure. Dry-run by default, supports real-time output and workspace filtering.

Default Branch

• Compares changes against main by default. Use --default-branch to override.

Parallel Processing

• Use --parallel N (max 4) to process modules in parallel. Ex: solarboat plan --parallel 3
• In --watch mode, parallelism is forced to 1 for clean output.

Watch Mode

• --watch streams real-time Terraform output. Great for debugging and monitoring.
• Without --watch, operations run silently for CI/CD cleanliness.

Timeout Handling

• Initialization: 5 min
• Planning: 10 min
• Apply: 30 min

---

⚙️ Configuration

Solarboat supports flexible configuration via JSON files.

Quick Start:

1. Create solarboat.json in your project root:

{
  "global": {
    "ignore_workspaces": ["dev", "test"],
    "var_files": ["global.tfvars"],
    "workspace_var_files": {
      "prod": ["prod.tfvars"]
    }
  },
  "modules": {
    "infrastructure/networking": {
      "ignore_workspaces": ["test"],
      "var_files": ["networking.tfvars"],
      "workspace_var_files": {
        "prod": ["networking-prod.tfvars"]
      }
    }
  }
}

2. Run Solarboat as usual. It auto-loads your config.

Environment-Specific Config:

SOLARBOAT_ENV=prod solarboat plan

Solarboat will look for solarboat.prod.json if set.

Config Precedence:

1. CLI arguments (highest)
2. Module config
3. Global config
4. Defaults (lowest)

More: See CONFIGURATION.md for full docs.

---

🧑‍💻 GitHub Actions Integration

Solarboat comes with a GitHub Action for CI/CD automation.

GitHub Token Requirements

The GitHub token is optional and only needed for:

• 📝 PR Comments: Automatic plan summaries posted to pull requests
• 📊 Enhanced Integration: Access to GitHub API features

Most common scenarios:

• ✅ Basic Usage: No token required for core functionality (scan, plan, apply)
• ✅ PR Comments: Use ${{ secrets.GITHUB_TOKEN }} (automatically provided by GitHub)
• ⚠️ Custom Permissions: Use custom token only if default permissions aren't sufficient

Basic Workflow (Minimal Setup):

name: Infrastructure CI/CD
on: [push, pull_request]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Scan for Changes
        uses: devqik/solarboat@v0.8.9
        with:
          command: scan

      - name: Plan Infrastructure
        if: github.event_name == 'pull_request'
        uses: devqik/solarboat@v0.8.9
        with:
          command: plan
          output-dir: terraform-plans
          # Add token for PR comments
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Apply Changes
        if: github.ref == 'refs/heads/main'
        uses: devqik/solarboat@v0.8.9
        with:
          command: apply
          apply-dryrun: false

Production Workflow (Full Features):

name: Infrastructure Automation
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write # For PR comments

jobs:
  infrastructure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Plan Infrastructure Changes
        if: github.event_name == 'pull_request'
        uses: devqik/solarboat@v0.8.9
        with:
          command: plan
          config: ./infrastructure/solarboat.json
          terraform-version: "1.8.0"
          solarboat-version: "v0.8.9"
          parallel: 3
          ignore-workspaces: dev,test
          output-dir: terraform-plans
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Apply Infrastructure Changes
        if: github.ref == 'refs/heads/main'
        uses: devqik/solarboat@v0.8.9
        with:
          command: apply
          apply-dryrun: false
          config: ./infrastructure/solarboat.json
          terraform-version: "1.8.0"
          parallel: 2
          continue-on-error: false

Pipeline-Supplied Commits (New Feature)

Solarboat now supports intelligent change detection with pipeline-supplied commit information for more reliable CI/CD workflows.

Automatic Detection (Recommended)

The GitHub Action automatically detects the appropriate commits based on the event:

• Pull Requests: Uses base.sha and head.sha from the PR
• Main Branch Pushes: Uses before and after commit hashes
• Local Mode: Falls back to checking recent commits (configurable)

Manual Commit Specification

For advanced use cases, you can manually specify commit ranges:

- name: Custom Commit Comparison
  uses: devqik/solarboat@v0.8.9
  with:
    command: plan
    base-commit: abc1234
    head-commit: def5678
    base-branch: main
    head-branch: feature/new-module

Local Development Mode

When no commit information is provided, Solarboat runs in local mode:

- name: Local Development Mode
  uses: devqik/solarboat@v0.8.9
  with:
    command: plan
    recent-commits: 5 # Check last 5 commits for changes

Action Inputs:

| Input | Description | Default | Required | | ------------------- | ---------------------------------------- | ----------------- | -------- | | command | Command to run (scan, plan, apply) | - | ✅ | | github_token | GitHub token for PR comments | - | ❌ | | config | Path to Solarboat configuration file | auto-detect | ❌ | | output-dir | Directory for plan files | terraform-plans | ❌ | | apply-dryrun | Run apply in dry-run mode | true | ❌ | | ignore-workspaces | Comma-separated workspaces to ignore | - | ❌ | | var-files | Comma-separated var files to use | - | ❌ | | path | Directory to scan for modules | . | ❌ | | all | Process all stateful modules | false | ❌ | | watch | Show real-time output | false | ❌ | | parallel | Number of parallel processes (max 4) | 1 | ❌ | | default-branch | Default git branch for comparisons | main | ❌ | | recent-commits | Recent commits to check (local mode) | 5 | ❌ | | base-commit | Base commit SHA for comparison | auto-detect | ❌ | | head-commit | Head commit SHA for comparison | auto-detect | ❌ | | base-branch | Base branch name for comparison | auto-detect | ❌ | | head-branch | Head branch name for comparison | auto-detect | ❌ | | solarboat-version | Solarboat CLI version to use | latest | ❌ | | terraform-version | Terraform version to use | latest