Branch Alias Validation Laravel Package

Getting Started

Minimal Steps

1. Installation: Add to composer.json under require-dev:

   "phpcq/branch-alias-validation": "^1.0"
   

   Run composer update.

2. First Run: Navigate to your project root and execute:

   ./vendor/bin/validate-branch-alias.php
   

   Optionally specify a custom Git repo path:

   ./vendor/bin/validate-branch-alias.php /path/to/repo
   

3. First Use Case: Integrate into a pre-merge GitHub Actions workflow to block PRs where feature branches lag behind the latest tag:

   - name: Validate branch against latest tag
     run: ./vendor/bin/validate-branch-alias.php
   

Implementation Patterns

Usage Patterns

1. CI/CD Integration:

   • GitHub Actions: Add as a required step in workflows for feature/* and release/* branches.

     jobs:
       validate-branch:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: ./vendor/bin/validate-branch-alias.php
     

   • GitLab CI: Use before_script to validate branches pre-merge.

     validate_branch:
       script:
         - ./vendor/bin/validate-branch-alias.php
       rules:
         - if: '$CI_MERGE_REQUEST_ID'
     

2. Local Development:

   • Pre-Push Hook: Add to .git/hooks/pre-push (symlink to the binary).

     #!/bin/bash
     ./vendor/bin/validate-branch-alias.php || exit 1
     git push origin HEAD:refs/for/$CI_BRANCH
     

   • Laravel Artisan Command: Wrap the binary for consistency:

     // app/Console/Commands/ValidateBranch.php
     public function handle() {
         $exitCode = shell_exec('php ' . base_path('vendor/bin/validate-branch-alias.php'));
         if ($exitCode !== 0) {
             $this->error('Branch validation failed!');
             exit(1);
         }
     }
     

3. Tag-Based Workflows:

   • Release Branches: Validate release/* branches against the latest minor/patch tag (e.g., v1.2.x must be ahead of v1.2.0).
   • Hotfix Branches: Ensure hotfix/* branches are ahead of the latest patch tag (e.g., v1.0.1).

4. Monorepo Support:

   • Validate branches in modular Laravel repos by specifying repo paths:

     ./vendor/bin/validate-branch-alias.php packages/auth
     ./vendor/bin/validate-branch-alias.php packages/api
     

Workflows

1. Feature Branch Validation:

   • Workflow: Developers create feature/x branches from develop. Before merging to develop, the branch must be ahead of the latest tag (e.g., v1.0.0).
   • Integration:

     # GitHub Actions example
     jobs:
       feature-validation:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v4
           - run: ./vendor/bin/validate-branch-alias.php
         if: "startsWith(github.ref, 'refs/pull/') && contains(github.head_ref, 'feature/')"
     

2. Release Gatekeeping:

   • Workflow: Block merges to main if the release branch (e.g., release/1.2) isn’t ahead of the latest tag (v1.2.0).
   • Integration:

     // app/Providers/AppServiceProvider.php
     public function boot() {
         if (app()->environment('production') && str_starts_with(request()->branch, 'release/')) {
             $exitCode = shell_exec('php ' . base_path('vendor/bin/validate-branch-alias.php'));
             if ($exitCode !== 0) {
                 abort(500, 'Release branch validation failed!');
             }
         }
     }
     

3. Tagging Automation:

   • Workflow: Use the package to prevent tagging if branches are misaligned, then auto-generate tags post-validation.
   • Example:

     # After validation passes
     git tag -a v1.2.0 -m "Release 1.2.0"
     git push origin v1.2.0
     

Integration Tips

1. Laravel-Specific:

   • Publish Config: Extend the package by publishing its config (if supported in future versions) via:

     php artisan vendor:publish --tag=branch-alias-validation
     

   • Event Listeners: Trigger validation on git:pre-push or deploy events:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         'git.pre-push' => [
             Commands\ValidateBranch::class,
         ],
     ];
     

2. Git Hooks:

   • Symlink the binary to .git/hooks/pre-push or .git/hooks/pre-commit:

     ln -s ../../vendor/bin/validate-branch-alias.php .git/hooks/pre-push
     chmod +x .git/hooks/pre-push
     

3. Custom Rules:

   • Whitelist Branches: Override default behavior by filtering branches in a wrapper script:

     #!/bin/bash
     BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
     if [[ "$BRANCH_NAME" != "main" && "$BRANCH_NAME" != "develop" ]]; then
         ./vendor/bin/validate-branch-alias.php
     fi
     

4. CI Optimization:

   • Cache Git tags to avoid repeated fetches:

     - name: Cache Git tags
       run: git fetch --tags
     - name: Validate branch
       run: ./vendor/bin/validate-branch-alias.php
     

Gotchas and Tips

Pitfalls

1. False Positives:

   • Issue: A release/ branch may legitimately lag behind tags during preparation (e.g., release/1.2 is behind v1.2.0 but will be updated before merging).
   • Fix: Whitelist branches or adjust validation logic in a wrapper script:

     if [[ "$(git rev-parse --abbrev-ref HEAD)" == release/* ]]; then
         echo "Skipping validation for release branches..."
         exit 0
     else
         ./vendor/bin/validate-branch-alias.php
     fi
     

2. Git Not Installed:

   • Issue: CI environments may lack Git, causing the binary to fail silently.
   • Fix: Add Git installation to CI setup:

     - name: Install Git
       run: sudo apt-get install -y git
     

3. Permission Errors:

   • Issue: Access denied to .git directory in shared environments (e.g., Docker, CI).
   • Fix: Ensure the user running the script has read access to the repo:

     chmod -R a+rX .git
     

4. Tag Naming Inconsistencies:

   • Issue: Tags like v1.0.0-rc1 may cause validation to fail if the package expects strict SemVer.
   • Fix: Customize tag filtering in a wrapper or fork the package to adjust regex patterns.

5. Large Repositories:

   • Issue: Git operations (e.g., git tag) may time out in CI for repos with >50k commits.
   • Fix: Shallow clone or limit fetched tags:

     git fetch --depth=1 --tags
     ./vendor/bin/validate-branch-alias.php
     

Debugging

1. Exit Codes:

   • 0: Validation passed (branch is ahead of the latest tag).
   • 1: Validation failed (branch is behind or no tags exist).
   • Use in CI to conditionally fail jobs:

     - name: Validate and fail if needed
       run: |
         if ! ./vendor/bin/validate-branch-alias.php; then
           echo "::error::Branch validation failed!"
           exit 1
         fi
     

2. Verbose Output:

   • The package outputs the latest tag and branch comparison. Redirect to a file for debugging:

     ./vendor/bin/validate-branch-alias.php > validation.log 2>&1
     

3. Dry Runs:

   • Test locally before CI integration to verify behavior:

     # Simulate a "bad" branch (detached HEAD)
     git checkout v1.0.0
     ./vendor/bin/validate-branch-alias.php  # Should fail
     

Config Quirks

1. No Built-in Configuration:
   • The package lacks a config file (e.g., `.branch-validation.json