README

A Laravel package for automatically pruning old deployment releases while preserving the current symlinked release.

Overview

When using deployment tools like Laravel Envoy with a releases directory structure, old releases can accumulate over time and consume disk space. This package automatically cleans up old releases while ensuring:

The currently active release (symlinked via current) is never deleted
A configurable number of recent releases are retained
Scheduled automatic cleanup runs daily (or on your custom schedule)
Safe operation with dry-run mode and logging

Installation

Via Packagist

composer require service-to/prune-releases

Laravel Auto-Discovery

The package will automatically register its service provider in Laravel 5.5+.

Publish Configuration

Publish the configuration file to customize settings:

php artisan vendor:publish --tag=prune-releases-config

This will create config/prune-releases.php in your application.

Configuration

Edit config/prune-releases.php to customize the package behavior:

return [
    // Path to your releases directory
    'releases_directory' => env('PRUNE_RELEASES_DIR', base_path('../releases')),

    // Number of recent releases to keep
    'keep' => env('PRUNE_RELEASES_KEEP', 5),

    // Path to the current symlink
    'current_symlink' => env('PRUNE_RELEASES_CURRENT', base_path('../current')),

    // When to run: 'daily', 'hourly', 'weekly', or a cron expression
    'schedule' => env('PRUNE_RELEASES_SCHEDULE', 'daily'),

    // Enable dry-run mode (won't actually delete anything)
    'dry_run' => env('PRUNE_RELEASES_DRY_RUN', false),

    // Enable detailed logging
    'logging' => env('PRUNE_RELEASES_LOGGING', true),
];

Environment Variables

You can also configure the package using environment variables in your .env file:

PRUNE_RELEASES_DIR=/var/www/your-app/releases
PRUNE_RELEASES_KEEP=5
PRUNE_RELEASES_CURRENT=/var/www/your-app/current
PRUNE_RELEASES_SCHEDULE=daily
PRUNE_RELEASES_DRY_RUN=false
PRUNE_RELEASES_LOGGING=true

Usage

Automatic Scheduled Pruning

The package automatically schedules the prune command to run based on your schedule configuration. Make sure your Laravel scheduler is running:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Manual Pruning

You can manually prune releases at any time:

php artisan releases:prune

Dry Run Mode

Test the pruning logic without actually deleting anything:

php artisan releases:prune --dry-run

Or set it in configuration:

PRUNE_RELEASES_DRY_RUN=true

Override Keep Count

Override the number of releases to keep for a single run:

php artisan releases:prune --keep=10

How It Works

Scans the releases directory for all release folders
Identifies the current active release by following the current symlink
Sorts releases by modification time (newest first)
Keeps the configured number of recent releases
Protects the current release from deletion (even if it's older than the keep threshold)
Deletes old releases that exceed the keep threshold
Logs all operations for auditing

Example Deployment Structure

/var/www/your-app/
├── current -> /var/www/your-app/releases/20241202120000
├── .env
├── storage/
└── releases/
    ├── 20241201120000/  <- Will be deleted (older than keep threshold)
    ├── 20241201140000/  <- Will be deleted
    ├── 20241201160000/  <- Kept (within threshold)
    ├── 20241201180000/  <- Kept (within threshold)
    ├── 20241202100000/  <- Kept (within threshold)
    ├── 20241202110000/  <- Kept (within threshold)
    └── 20241202120000/  <- Kept (current release - NEVER deleted)

With keep=5, the package will:

Keep the 5 most recent releases
Ensure the current symlinked release is preserved
Delete releases 20241201120000 and 20241201140000

Safety Features

Current Release Protection: The release pointed to by the current symlink is always preserved, even if it's older than the configured threshold
Dry Run Mode: Test configuration without deleting anything
Detailed Logging: All operations are logged for auditing
Interactive Confirmation: Manual runs require confirmation before deletion
Error Handling: Graceful error handling with detailed error messages

Troubleshooting

"Releases directory does not exist"

Ensure the releases_directory path in your config points to the correct location. Check:

ls -la /var/www/your-app/releases

"Current symlink not found"

The package will still work but won't be able to protect the current release. Verify your symlink:

ls -la /var/www/your-app/current

Scheduler Not Running

Ensure your Laravel scheduler cron job is configured:

crontab -e

Add:

* * * * * cd /var/www/your-app/current && php artisan schedule:run >> /dev/null 2>&1

Check Scheduled Tasks

Verify the prune task is scheduled:

php artisan schedule:list

You should see releases:prune listed.

Testing

Run the test suite:

composer test

Requirements

PHP 8.0 or higher
Laravel 8.0 or higher

License

The MIT License (MIT). Please see License File for more information.

Credits

ServiceTo

Support

For issues, questions, or contributions, please visit the GitHub repository.

service-to / prune-releases

Maintainers

Details