Github Actions Watcher Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer global require spatie/github-actions-watcher
   

   Ensure $HOME/.composer/vendor/bin is in your PATH or use the full path to actions-watcher.

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

   actions-watcher
   

   The tool auto-detects the GitHub repo/branch from your local .git config.

3. Authentication:

   • If unauthenticated, the CLI prompts for a GitHub token (store it in ~/.config/spatie/github-actions-watcher for reuse).
   • Generate a token via GitHub Settings > Developer Settings > Personal Access Tokens with repo scope.

First Use Case: Real-Time Workflow Monitoring

Monitor all workflows triggered by a git push:

git push origin main && actions-watcher

• Watch workflows across all branches (e.g., PRs) with:

  actions-watcher --all-branches
  

• Filter by a specific workflow file (e.g., phpunit.yml):

  actions-watcher --workflow=phpunit.yml
  

Implementation Patterns

Workflow Integration in Laravel CI/CD

1. Post-Deployment Verification: Add to your deploy.php (Deployer) or after-deploy script:

   cd /path/to/repo && actions-watcher --exit-code-only
   

   Exit code 1 = failed workflows; 0 = all passed.

2. Scheduled Monitoring: Use Laravel’s schedule to poll workflows nightly (e.g., for long-running jobs):

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule) {
       $schedule->command('actions-watcher --exit-code-only --poll-interval=300')
                ->dailyAt('03:00');
   }
   

3. Slack/Teams Notifications: Pipe output to a webhook (e.g., via curl):

   actions-watcher --json | jq -r '.workflows[] | "Workflow \(.name) status: \(.status)"' | curl -X POST -H 'Content-Type: text/plain' --data-binary @- https://hooks.slack.com/...
   

Advanced Patterns

• Multi-Repository Monitoring: Use --repo to switch contexts:

  actions-watcher --repo=spatie/laravel-activitylog
  

• Custom Output Formats: Export to JSON/CSV for parsing:

  actions-watcher --json > workflows.json
  

  Parse in Laravel:

  $workflows = json_decode(file_get_contents('workflows.json'), true);
  foreach ($workflows['workflows'] as $wf) {
      if ($wf['status'] === 'failure') {
          Log::error("Workflow {$wf['name']} failed", $wf['run']['details_url']);
      }
  }
  

• Integration with Laravel Tests: Test workflows in phpunit.xml:

  <php>
      <env name="GITHUB_TOKEN" value="your_token_here"/>
  </php>
  <listeners>
      <listener class="Spatie\GitHubActionsWatcher\TestListener" file="vendor/spatie/github-actions-watcher/src/TestListener.php"/>
  </listeners>
  

Gotchas and Tips

Pitfalls

1. Rate Limiting:

   • GitHub’s API has rate limits. For high-frequency polling, use --poll-interval=60 (default: 30s).
   • Cache tokens in ~/.config/spatie/github-actions-watcher to avoid repeated logins.

2. Workflow Detection:

   • The tool ignores workflows in forked repos unless you explicitly target them with --repo.
   • Self-hosted runners: Workflows using them may show as "in_progress" longer. Add --ignore-self-hosted to filter them out.

3. Exit Codes:

   • actions-watcher exits with 1 if any workflow fails. Use --exit-code-only in scripts to avoid false positives from interactive output.

4. Branch Auto-Detection:

   • If in a detached HEAD state, the tool defaults to main. Specify --branch explicitly:

     actions-watcher --branch=feature/x
     

Debugging

• Verbose Mode:

  actions-watcher -v
  

  Reveals API calls and polling intervals.

• API Debugging: Check GitHub API responses directly:

  curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/repos/OWNER/REPO/actions/workflows
  

• Token Issues: Regenerate tokens if you see 403 Forbidden. Ensure the token has repo and workflow scopes.

Extension Points

1. Custom Polling Logic: Override the default 30s interval via --poll-interval or extend the PHP class:

   // app/Providers/AppServiceProvider.php
   use Spatie\GitHubActionsWatcher\GitHubActionsWatcher;
   
   public function boot() {
       GitHubActionsWatcher::setPollInterval(120); // 2 minutes
   }
   

2. Webhook Alternative: For real-time updates, pair with GitHub’s Actions API webhooks and Laravel’s queue:listen:

   // routes/web.php
   Route::post('/github-actions-webhook', [WebhookHandler::class, 'handle']);
   

3. CI-Specific Config: In .github-actions-watcher.php (if supported in future versions), define repo-specific defaults:

   return [
       'default_branch' => 'dev',
       'ignored_workflows' => ['deploy.yml'],
   ];
   

Pro Tips

• Combine with gh CLI: Use GitHub’s CLI for repo switching and pipe to actions-watcher:

  gh repo clone spatie/laravel-activitylog && cd laravel-activitylog && actions-watcher
  

• Laravel Forge/Envoyer: Add to your after_deploy script to verify deployments:

  cd /var/www/app && actions-watcher --exit-code-only
  

• Artisan Command: Create a custom command for team-wide access:

  php artisan make:command MonitorWorkflows
  

  // app/Console/Commands/MonitorWorkflows.php
  public function handle() {
      $this->call('actions-watcher', [
          '--repo' => $this->argument('repo'),
          '--exit-code-only' => true,
      ]);
  }