Download the PHP package hopheartsceo/laravel-release-guard without Composer

Laravel Release Guard

Laravel Release Guard is a static deployment compatibility analyzer for Laravel applications.

It checks supported database changes for incompatibilities between the release you are preparing and the application version that is already running during a rolling or zero-downtime deployment.

It does not execute migrations, boot the previous application revision, or run application endpoints.

Instead, it compares the previous Git revision with the candidate working tree and reports evidence-backed compatibility findings.

Why

During a rolling deployment, the old and new application versions may run at the same time.

A migration that is valid for the new code can still break requests handled by the previous release.

For example:

while the currently deployed release still contains:

Laravel Release Guard detects this compatibility problem before deployment.

Installation

Install the package as a development / CI dependency:

Laravel package discovery registers the service provider automatically.

Quick Start

Compare the candidate working tree against the revision currently deployed:

You can use any Git revision that resolves to a commit:

For CI or other machine consumers:

How It Works

Laravel Release Guard analyzes the previous application revision directly from Git without checking it out.

Candidate migrations come from changes in the current working tree relative to the selected base revision, including supported untracked migration files.

Database Rules

Rules can be individually disabled in configuration.

Findings

Every finding has two important dimensions:

Severity

• BLOCKER — deployment compatibility problem
• WARNING — requires review
• INFO — informational result

Confidence

• DEFINITE — supported static evidence establishes the result
• PROBABLE — strong evidence exists but certainty is limited
• UNKNOWN — the analyzer intentionally cannot prove the result

Laravel Release Guard prefers UNKNOWN over fabricated certainty.

Only a BLOCKER with DEFINITE confidence fails compatibility CI.

Exit Codes

The command uses a stable CI-oriented exit-code contract:

Exit code 0 does not mean that a deployment has been proven universally safe.

The precise guarantee is:

No incompatible changes detected within the analyzed scope.

Console Output

A successful analysis can look like:

A detected compatibility problem can look like:

JSON Output

Use:

The result is machine-readable:

When a definite blocker exists, status becomes:

Analyzer or Git failures also remain machine-readable when JSON output is requested:

Configuration

Publish the configuration file:

The default configuration is:

Application and migration paths can be adjusted for non-standard project layouts.

Conservative Analysis

Laravel Release Guard does not assume that dynamic Laravel behavior is deterministic.

For example, a direct Query Builder insert with a statically known payload can provide strong evidence about the columns being written.

An Eloquent call such as:

does not necessarily reveal the final SQL insert columns.

Mass-assignment configuration, model defaults, events, mutators, and other model behavior can affect persistence.

For cases like this, Laravel Release Guard intentionally reports uncertainty instead of promoting incomplete evidence to a definite blocker.

For DB005, supported write paths include direct Query Builder insert / insertGetId, the existing Eloquent create family, and a narrow fresh-instance Eloquent save() pattern:

Fresh-instance save() coverage is intentionally limited to direct construction of a known model, optional supported assignments on the same receiver, and a later direct save() on that receiver. It is reported as WARNING / UNKNOWN, remains non-blocking by itself, and does not change Query Builder insert classification.

Loaded-model saves, ambiguous receiver provenance, aliases, helper-created models, factories, relationship saves, dependency injection, container resolution, dynamic model classes, saveOrFail(), and push() are not treated as fresh inserts.

The same principle applies to dynamic table names, dynamic column names, dynamic write payloads, and unsupported raw migration operations.

Analysis Scope

Laravel Release Guard focuses on database compatibility during rolling and zero-downtime Laravel deployments.

It statically analyzes supported Laravel migration operations and supported application database usage patterns.

It is not intended to prove every possible deployment risk.

In particular, it does not execute application code or migrations, and it does not claim to model every runtime, infrastructure, operational, locking, data-backfill, queue, cache, or serialized-payload compatibility concern.

These are separate deployment concerns and may be addressed by future analysis capabilities.

Git Safety

Laravel Release Guard treats Git input as untrusted analyzer input.

Revision arguments are verified as commits before object lookup.

Working-tree files are restricted to the repository boundary, including protection against traversal, absolute-path access, and symlink escape.

Git failures are exposed through concise analyzer errors rather than raw process command output.

CI Example

A minimal GitHub Actions step can run:

The command naturally fails the CI job only when a definite blocker is detected or when analysis itself cannot complete.

Requirements

• PHP 8.1 or later
• Laravel 10, 11, 12, or 13
• Git available in the execution environment

Development

Install dependencies:

Run the complete test suite:

Design Principle

The project follows one central rule:

Prefer UNKNOWN to invented certainty.

A static deployment analyzer is useful only when teams can trust the distinction between what it knows and what it cannot prove.

License

Laravel Release Guard is open-source software licensed under the MIT License.