README

A Laravel package that checks your application for deployment risks before production release.

laravel-deploy-guard provides a CLI-first readiness command for local checks, staging validation, and CI/CD pipelines. It inspects common Laravel deployment risks and reports clear pass, warning, fail, or skipped results.

It does not deploy your application, run migrations, change environment files, or inspect server infrastructure.

Documentation

• Usage guide
• CI/CD guide
• Configuration reference
• Checks reference
• JSON output reference
• Custom checks
• Testing and quality tools
• Troubleshooting
• FAQ
• Security policy
• Contribution guide
• Change log

Installation

Install the package as a development dependency:

composer require satheez/laravel-deploy-guard --dev

Publish the configuration file:

php artisan vendor:publish --tag=deploy-guard-config

Run the deployment checks:

php artisan deploy:guard

Quick Start

Run every enabled check:

php artisan deploy:guard

Run in CI mode:

php artisan deploy:guard --ci

Return JSON:

php artisan deploy:guard --json

Run selected categories or check keys:

php artisan deploy:guard --only=env,cache,migrations

Skip selected categories or check keys:

php artisan deploy:guard --except=mail,queue

Fail when warnings exist:

php artisan deploy:guard --fail-on=warning

Evaluate checks against a target environment:

php artisan deploy:guard --env=production

Example Output

Laravel Deploy Guard

Environment: production
Checks run: 22
Passed: 17
Warnings: 3
Failed: 2
Skipped: 0

FAILURES
[FAIL] env.app_debug
APP_DEBUG is enabled in a production environment.
Suggestion: Set APP_DEBUG=false before deploying to production.

WARNINGS
[WARNING] queue.connection
Queue connection is sync in production.
Suggestion: Use database, redis, sqs, or another async queue driver.

Exit Codes

Exit Code	Meaning
0	No failed checks, or warnings only when warnings are allowed
1	One or more checks failed
2	One or more warnings exist and --fail-on=warning is enabled

If failures and warnings both exist, the command returns 1.

Available Checks

Category	Checks
env	env.app_env, env.app_key, env.app_debug, env.app_url
database	database.default_connection, database.connection
migrations	migrations.pending
queue	queue.connection, queue.failed_jobs
cache	cache.driver, cache.config, cache.routes, cache.views
storage	storage.directory_writable, storage.bootstrap_cache_writable, storage.public_link
mail	mail.mailer, mail.production_mailer
filesystem	filesystem.default_disk, filesystem.default_disk_config, filesystem.cloud_disk
scheduler	scheduler.validation

See the checks reference for behavior, status rules, and suggestions.

Configuration

The published config file is config/deploy-guard.php.

return [
    'enabled' => env('DEPLOY_GUARD_ENABLED', true),

    'production_environments' => [
        'production',
        'prod',
    ],

    'checks' => [
        'env' => true,
        'database' => true,
        'migrations' => true,
        'queue' => true,
        'cache' => true,
        'storage' => true,
        'mail' => true,
        'filesystem' => true,
        'scheduler' => true,
    ],

    'allow' => [
        'sync_queue_in_production' => false,
        'array_cache_in_production' => false,
        'log_mailer_in_production' => false,
        'array_mailer_in_production' => false,
    ],
];

See the configuration reference for all options.

JSON Output

Use --json for machine-readable reports:

php artisan deploy:guard --ci --json

See the JSON output reference for the schema and examples.

Custom Checks

Applications can register custom checks through config/deploy-guard.php:

'custom_checks' => [
    App\DeployGuard\SearchIndexReadyCheck::class,
],

See custom checks for a complete example.

Development

Install dependencies:

composer install

Run the full local quality suite:

composer test
vendor/bin/pint --test
composer rector:test
composer analyse

The package uses Pest, Pint, Rector, and Larastan. See testing and quality tools.

Security

Reports never include secret values such as application keys, database passwords, mail passwords, tokens, or private keys. See SECURITY.md.

License

The MIT License.