Scotty Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Ecosystem Alignment: Scotty is a drop-in replacement for Laravel Envoy, leveraging the same annotation-based syntax (@servers, @task, @macro) and Blade templating support. This ensures seamless integration with Laravel deployments, CI/CD pipelines, and existing SSH workflows.
• Task Orchestration: The package excels at remote task execution (e.g., deployments, database migrations, cache clearing) via SSH, making it ideal for multi-server Laravel applications (e.g., web, queue, database servers).
• Idempotency & Safety: Built-in features like --pretend, --continue, and confirmation prompts (confirm="...") align with Laravel’s emphasis on reliable, auditable deployments.
• Extensibility: Supports custom SSH configurations (via ~/.ssh/config) and dynamic options (CLI/env vars), enabling integration with Laravel’s .env system or Forge/Sail environments.

Integration Feasibility

• Minimal Laravel-Specific Dependencies: Scotty is language-agnostic (PHP/Laravel-aware but not dependent). It can be used in any PHP project or standalone.
• Envoy Compatibility: Existing Laravel Envoy scripts can be migrated with minimal changes (replace envoy run with scotty run).
• CI/CD Integration: Works natively with GitHub Actions, GitLab CI, and Laravel Forge (via SSH keys). Example:

  # GitHub Actions
  - name: Deploy
    run: ./scotty run deploy --branch=${{ github.ref_name }}
  

• Local Development: Supports local= servers for testing deploy scripts before production.

Technical Risk

Key Questions for TPM

1. Deployment Complexity:

   • How many servers/tasks are in the current workflow? Scotty’s macro system scales well for 5–50 tasks, but complex workflows may need custom error handling.
   • Example: "Do we need to roll back failed migrations automatically?" → Extend with scotty run rollback or integrate with Laravel’s migrate:rollback.

2. Security:

   • Are SSH keys managed via Laravel Forge, Sail, or manual ~/.ssh/config? Scotty inherits this setup.
   • Should sensitive commands (e.g., php artisan key:generate) be excluded from logs? Use --summary or redirect output to /dev/null.

3. Monitoring:

   • How will deployment success/failure be tracked? Scotty’s exit codes can be captured in CI or logged to Laravel’s logs directory.
   • Example:

     if ! ./scotty run deploy --summary; then
       echo "Deployment failed!" | tee -a storage/logs/deploy-failures.log
     fi
     

4. Team Adoption:

   • Is the team familiar with bash scripting? Scotty’s syntax is simple, but Blade templates require Laravel knowledge.
   • Should interactive features (pause/resume) be disabled in CI? Use --no-interaction flag.

5. Future-Proofing:

   • Will Scotty’s annotation syntax evolve? Monitor GitHub for breaking changes (e.g., Blade support deprecation).
   • Should we containerize Scotty (e.g., Docker) for air-gapped environments? The PHAR is portable, but a Docker image could simplify setup.

Integration Approach

Stack Fit

Migration Path

1. Assessment Phase:

   • Audit existing Envoy scripts or manual SSH workflows.
   • Identify critical tasks (e.g., deploy, rollback, database backups) to prioritize.

2. Pilot Migration:

   • Convert one deployment script (e.g., deploy.sh → Scotty.sh).
   • Test with --pretend and --summary modes.
   • Example migration:

     # Before (Envoy)
     @servers(['web' => 'deploy@example.com'])
     @task('deploy', ['on' => 'web'])
     run(['cd /var/www/app', 'git pull origin main']);
     
     # After (Scotty)
     # @servers web=deploy@example.com
     # @task on:web
     deploy() {
         cd /var/www/app
         git pull origin main
     }
     

3. Full Rollout:

   • Replace envoy run with scotty run in CI/CD pipelines.
   • Update local development workflows (e.g., scotty ssh instead of manual SSH).
   • Deprecate legacy scripts via CI linting (fail builds if envoy commands remain).

4. Advanced Integration:

   • Laravel Artisan Command: Create a custom command to wrap Scotty:

     // app/Console/Commands/Deploy.php
     public function handle() {
         $exitCode = shell_exec('php artisan scotty run deploy --summary');
         if ($exitCode !== 0) $this->error('Deployment failed!');
     }
     

   • Event Listeners: Log deployments to a database or Slack:

     // app/Listeners/LogDeployment.php
     public function handle() {
         DeployLog::create([
             'status' => $this->scottyExitCode === 0 ? 'success' : 'failed',
             'branch' => $_ENV['BRANCH'],
         ]);
     }
     

Compatibility

Sequencing

1. Phase 1: Replace Envoy (2–4 weeks)

   • Migrate scripts; test in staging.
   • Update CI/CD to use Scotty.

2. Phase 2: Enhance Workflows (1–2 weeks)

   • Add dynamic options (e.g., --branch, --env=production).
   • Implement rollback macros or pre-deploy checks.

3. Phase 3: Monitor & Optimize (Ongoing)

   • Track failure rates; adjust --continue usage.
   • Explore parallelization for non-critical tasks.

Operational Impact

Maintenance

• Pros:
  • Single PHAR file: No Composer dependencies; easy to update (curl -L https://.../scotty -o scotty).
  • Self-documenting: Scotty.sh files are version-controlled and readable.
  • Vendor Support: Spatie provides active maintenance (last release: 2026-04-27).
• Cons:
  • Bash Scripting: Requires basic shell knowledge for complex tasks.