Documentation

blight is a PHP CLI tool that detects version and environment drift between your local machine and CI/CD environments. Run one command to know exactly why your local build passes but CI fails.

Introduction

Most CI failures caused by environment mismatch are invisible until they hit the build server. blight compares your local environment against GitHub Actions logs in real time — surfacing PHP version mismatches, missing Node.js, and ENV variable drift before you push.

• Parse GitHub Actions log files for errors, warnings, and failed steps
• Compare local PHP, Node.js, and ENV state against what CI used
• Classify mismatches as CRITICAL, WARNING, or INFO
• Output as interactive terminal tables or machine-readable JSON

Installation

Clone and run locally

git clone https://github.com/blight-dev/blight.git
cd blight
composer install
php bin/blight --version

Composer global install (once on Packagist)

composer global require blight/blight
blight --version

Requirements: PHP 8.2+, Composer 2.x, ext-json

Quick Start

The fastest way to catch a CI mismatch:

php bin/blight info

php bin/blight parse --log /path/to/github-actions.log

php bin/blight compare --log /path/to/github-actions.log

php bin/blight report

blight info

$ php bin/blight info
blight.dev – Local Environment Inspector
=========================================
PHP Version   8.2.0
Node Version  20.11.0
OS            Linux x86_64
Branch        main / abc1234
DATABASE_URL  [REDACTED]

blight parse

$ php bin/blight parse --log examples/ci-major-mismatch.log
Steps: Set up PHP ✓, Set up Node.js ✓, Run tests ✗
Errors (2): PHP Fatal error in Util.php:42, exit code 255
Summary: 3 steps, 1 failed, 2 errors

blight compare

┌──────────┬─────────────────┬───────────┬────────┬─────────────────────────────────────┐
│ Severity │ Key             │ Local     │ CI     │ Message                             │
├──────────┼─────────────────┼───────────┼────────┼─────────────────────────────────────┤
│ CRITICAL │ PHP Version     │ 8.2.0     │ 7.4.33 │ Major version mismatch — will fail  │
│ WARNING  │ Node.js Version │ not found │ 18.1.0 │ CI uses Node.js, not installed here │
└──────────┴─────────────────┴───────────┴────────┴─────────────────────────────────────┘

blight report

blight history Paid

blight init

$ php bin/blight init
? API key (leave blank for free plan): blight_pro_xxxxxxxxx
? Default repo name: my-app
? Enable Slack alerts? No
✔ Created .blight.json

Configuration — .blight.json

blight looks for a .blight.json file in the current directory. Create one with blight init or manually:

{
  "api_key": "blight_pro_xxxxxxxxxxxxxxxx",
  "repo": "my-app",
  "alerts": {
    "slack_webhook": "https://hooks.slack.com/services/...",
    "discord_webhook": ""
  }
}

Output Formats

All commands support --output json for structured machine-readable output. Useful for scripting, CI integration, or dashboards.

{
  "command": "compare",
  "repo": "my-app",
  "timestamp": "2026-04-09T12:00:00Z",
  "mismatches": [
    {
      "severity": "CRITICAL",
      "key": "PHP Version",
      "local": "8.2.0",
      "ci": "7.4.33",
      "message": "Major PHP version mismatch"
    }
  ],
  "summary": { "critical": 1, "warning": 0, "info": 0 }
}

Quiet Mode (-q)

Pass -q to any command to get a single-line summary. Ideal for shell scripts and CI pipelines.

$ php bin/blight compare --log ci.log -q
CRITICAL: 1, WARNING: 1, Total: 2

$ php bin/blight parse --log ci.log -q
Errors: 2, Warnings: 0, Failed steps: 1

Webhook Alerts Paid

blight can send a webhook notification every time a compare finds mismatches. Supports Slack and Discord (any service accepting JSON POST).

Configure via .blight.json

{
  "api_key": "blight_pro_xxxxxxxxxxxxxxxx",
  "repo": "my-app",
  "alerts": {
    "slack_webhook": "https://hooks.slack.com/services/T.../B.../xxx",
    "discord_webhook": "https://discord.com/api/webhooks/..."
  }
}

Or pass inline with compare

php bin/blight compare --log ci.log \
  --alert slack \
  --webhook-url https://hooks.slack.com/services/...

GitHub Actions Integration

blight ships with a ready-to-use GitHub Actions pipeline at .github/workflows/ci.yml. It runs on every push and pull request, covering lint, static analysis, and blight's own dogfood steps.

name: CI

on:
  push:
  pull_request:

jobs:
  build:
    name: PHP ${{ matrix.php-version }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        php-version: ["8.2"]

    steps:
      - uses: actions/checkout@v4

      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-version }}

      - name: Validate composer.json
        run: composer validate --strict

      - name: Cache Composer packages
        uses: actions/cache@v4
        with:
          path: vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('composer.lock') }}

      - name: Install dependencies
        run: composer install --no-interaction --prefer-dist

      - name: Lint PHP syntax
        run: find src/ -name "*.php" -print0 | xargs -0 -n1 php -l

      - name: PHPStan static analysis
        run: vendor/bin/phpstan analyse --no-progress --error-format=github

      - name: blight — parse sample log (dogfood)
        continue-on-error: true
        run: php bin/blight parse --log examples/ci-sample.log

      - name: blight — compare local vs CI sample (dogfood)
        continue-on-error: true
        run: php bin/blight compare --log examples/ci-sample.log

Using blight in your own CI

To use blight as a drift-detection step in any existing GitHub Actions workflow, add a step that downloads your actual CI log and runs compare:

- name: Detect environment drift with blight
  run: |
    php bin/blight compare --log "${{ runner.temp }}/ci-run.log" -q
  continue-on-error: true

Sample Log Format

blight parses GitHub Actions log files downloaded from the Actions tab of your repository. The parser looks for specific patterns:

The examples/ directory contains two reference logs you can use for testing:

• examples/ci-sample.log — A realistic 7-step log with a failed test step and error lines
• examples/ci-major-mismatch.log — A log showing PHP 7.4 vs 8.x major version mismatch

php bin/blight parse --log examples/ci-sample.log
php bin/blight compare --log examples/ci-major-mismatch.log

Pre-push Git Hook

Catch CI drift before you push by wiring blight into a Git pre-push hook. Save your latest CI log and compare it automatically on every push:

#!/bin/sh
# blight pre-push hook — abort if CRITICAL drift is found
LOG="$HOME/.blight/last-ci.log"
if [ -f "$LOG" ]; then
  RESULT=$(php bin/blight compare --log "$LOG" -q 2>&1)
  echo "$RESULT"
  if echo "$RESULT" | grep -q "CRITICAL: [1-9]"; then
    echo "blight: CRITICAL environment drift detected. Fix before pushing."
    exit 1
  fi
fi
exit 0

chmod +x .git/hooks/pre-push

PHPStan Integration

blight uses PHPStan for static analysis at level 5. The configuration lives in phpstan.neon at the project root:

includes:
    - phpstan-baseline.neon

parameters:
    level: 5
    paths:
        - src/

The phpstan-baseline.neon file baselines pre-existing errors in the codebase so that only new code must be clean. To regenerate the baseline after fixing errors:

vendor/bin/phpstan analyse --generate-baseline --memory-limit=512M

PHPStan runs automatically on every push via the CI pipeline and outputs annotations directly in GitHub pull requests using --error-format=github.

Multi-Language Support

blight supports English, Turkish, and Simplified Chinese output. Set your preferred language via CLI flag, config file, or environment variable.

Usage

php bin/blight info --lang tr
php bin/blight compare --log ci.log --lang zh

{
    "lang": "tr"
}

BLIGHT_LANG=tr php bin/blight info

Priority Order

1. --lang CLI flag
2. .blight.json "lang" field
3. BLIGHT_LANG environment variable
4. Default: en (English)

Supported Languages

Free Plan

• 5 analyses per repository
• 1 repository
• All commands available
• History limited to last 5 entries
• No JSON history export

Paid Plan

• Unlimited analyses
• Unlimited repositories
• Full history with filtering
• JSON history export
• Slack & Discord alert webhooks
• Priority support

Set your API key in .blight.json or via blight init to activate paid features.