Codeship Scripts Laravel Package

Getting Started

Minimal Steps

1. Installation Clone the repository into your project’s bin/ directory:

   git clone https://github.com/chaplean/codeship-scripts.git bin/codeship-scripts
   

   Ensure scripts are executable:

   chmod +x bin/codeship-scripts/*.sh
   

2. First Use Case: Running PHPUnit Tests Use phpunit.sh in your CI pipeline (e.g., Codeship) to execute tests after MySQL is ready:

   ./bin/codeship-scripts/phpunit.sh --parallel=4
   

   • Replace 4 with the number of parallel processes (optional).
   • The script auto-detects MySQL readiness via services-waiting.sh.

3. First Use Case: Deploying with Capistrano Configure deploy.sh for your environment:

   ./bin/codeship-scripts/deploy.sh --env=production --user=deploy
   

   • Requires a config/deploy.rb file (Capistrano-compatible).
   • Use --dry-run to test without deploying.

Implementation Patterns

Workflows

1. CI Pipeline Integration

   • Order of Execution: Always run services-waiting.sh before database-dependent scripts (e.g., phpunit.sh or migrations).

     ./bin/codeship-scripts/services-waiting.sh --service=mysql
     ./bin/codeship-scripts/phpunit.sh
     

   • Parallel Testing: Split PHPUnit tests into chunks for faster CI runs:

     ./bin/codeship-scripts/phpunit.sh --parallel=2 --chunk=1  # Run chunk 1 of 2
     

2. Environment-Specific Deployments

   • Use deploy-htaccess.sh for environment-specific .htaccess files (e.g., prod.htaccess vs. staging.htaccess):

     ./bin/codeship-scripts/deploy-htaccess.sh --env=staging
     

   • Combine with deploy.sh for full deployments:

     ./bin/codeship-scripts/deploy.sh --env=staging && ./bin/codeship-scripts/deploy-htaccess.sh --env=staging
     

3. Docker Service Dependencies

   • Wait for multiple services (e.g., MySQL + Redis) before running tests:

     ./bin/codeship-scripts/services-waiting.sh --service=mysql --service=redis
     

Integration Tips

• Laravel-Specific:

  • For Laravel’s .env management, prepend deployment steps to copy .env.example and generate keys:

    cp .env.example .env && php artisan key:generate && ./bin/codeship-scripts/deploy.sh
    

  • Use phpunit.sh with Laravel’s test configuration:

    ./bin/codeship-scripts/phpunit.sh --config=phpunit.xml --parallel=4
    

    (Note: Requires passing --config explicitly if not using default phpunit.xml.)

• Codeship Configuration:

  • Add scripts to your codeship-services.yml or codeship-steps.yml:

    - service: app
      command: ./bin/codeship-scripts/services-waiting.sh --service=mysql && ./bin/codeship-scripts/phpunit.sh
    

Gotchas and Tips

Pitfalls

1. Hardcoded Paths

   • Scripts assume bin/codeship-scripts/ is in your $PATH or called with relative paths. Avoid moving the directory without updating references.

2. MySQL Credentials

   • services-waiting.sh and phpunit.sh rely on environment variables (DB_HOST, DB_DATABASE, etc.). Ensure they are set in your CI environment:

     export DB_HOST=mysql && ./bin/codeship-scripts/phpunit.sh
     

3. Capistrano Dependencies

   • deploy.sh requires:
     • A valid config/deploy.rb (Capistrano 3.x syntax).
     • SSH access to the target server with the specified user (--user flag).
   • Debug with --dry-run:

     ./bin/codeship-scripts/deploy.sh --dry-run --env=production
     

4. Parallel Testing Quirks

   • --parallel in phpunit.sh splits tests by file order. For consistent chunks, sort your test files or use --chunk:

     ./bin/codeship-scripts/phpunit.sh --parallel=2 --chunk=1
     

5. HTAccess Overwrites

   • deploy-htaccess.sh assumes .htaccess files are named <env>.htaccess (e.g., staging.htaccess). Customize the script if your naming differs.

Debugging

• Verbose Output: Add -v to any script for debugging:

  ./bin/codeship-scripts/phpunit.sh -v
  

• Service Waiting Timeout: Adjust the timeout in services-waiting.sh (default: 30 seconds) by editing the script or passing a custom timeout:

  ./bin/codeship-scripts/services-waiting.sh --service=mysql --timeout=60
  

Extension Points

1. Custom Services Modify services-waiting.sh to support additional services (e.g., Elasticsearch) by adding logic to the check_service function.

2. PHPUnit Configuration Extend phpunit.sh to support custom test suites or plugins:

   ./bin/codeship-scripts/phpunit.sh --group=unit,integration
   

   (Requires editing the script to pass --group to PHPUnit.)

3. Post-Deploy Hooks Append commands to deploy.sh for Laravel-specific tasks (e.g., cache clearing):

   ./bin/codeship-scripts/deploy.sh --env=production && ssh user@server "cd /path/to/app && php artisan cache:clear"
   

Configuration Quirks

• Environment Variables: Scripts prioritize environment variables over hardcoded values. Override defaults in your CI:

  export CAPISTRANO_USER=deploy && ./bin/codeship-scripts/deploy.sh
  

• Shebang Lines: Ensure scripts use #!/bin/bash (not #!/usr/bin/env bash) for consistency across CI environments.