Claude Code for PR Status Check Workflow Tutorial

Pull request status checks are essential for maintaining code quality in any development workflow. Whether you’re managing a small team or coordinating across an entire organization, automated PR status checks help ensure that only properly reviewed and tested code makes it into your main branch. This tutorial demonstrates how to build powerful PR status check workflows using Claude Code, using GitHub’s API and automation capabilities to streamline your development process.

Understanding PR Status Checks

Before diving into implementation, it’s important to understand what PR status checks actually do. When you create a pull request in GitHub, various systems can report their status back to that PR. These statuses appear as check runs, check suites, and commit statuses, providing immediate visual feedback about whether your code meets certain criteria.

GitHub provides several types of status reporting:

Commit statuses: Simple pass/fail indicators that appear on commits
Check runs: Detailed results from CI/CD systems and other tools
Check suites: Collections of check runs that run on the same commit

Claude Code can interact with all of these through the GitHub API, enabling you to create sophisticated monitoring and automation workflows.

Setting Up GitHub API Access

To interact with PR statuses programmatically, you’ll need to authenticate with GitHub’s API. The recommended approach is using a personal access token with appropriate scopes. Create a token with the repo scope for full repository access, or public_repo for public repositories only.

Store your token securely as an environment variable:

export GITHUB_TOKEN="your_personal_access_token_here"

In your Claude Code workflow, you can reference this using environment variable substitution. This keeps your credentials secure and out of your codebase.

Building the Status Check Workflow

Let’s create a Claude Code skill that monitors PR status checks and reports their state. We’ll use a skill that can be invoked whenever you need to check the status of a pull request.

First, define the skill structure with appropriate tools:

name: pr-status-check
description: Check pull request status and wait for required checks

The skill should use GitHub’s API endpoint to fetch the combined status for a commit:

async function getPRStatus(owner, repo, prNumber) {
  const { data: pr } = await github.rest.pulls.get({
    owner,
    repo,
    pull_number: prNumber
  });
  
  const { data: checks } = await github.rest.checks.listForRef({
    owner,
    repo,
    ref: pr.head.sha,
    status: "completed"
  });
  
  return {
    sha: pr.head.sha,
    status: checks.check_runs.map(run => ({
      name: run.name,
      status: run.conclusion,
      url: run.html_url
    }))
  };
}

This function retrieves all completed check runs for the PR’s latest commit, allowing you to see which checks have passed or failed.

Creating a Wait-for-Checks Pattern

A common workflow pattern is waiting for all required checks to complete before proceeding. This is particularly useful in automation scripts where you need to ensure CI pipelines have finished before taking further action.

Here’s how to implement a wait-for-checks function:

async function waitForChecksComplete(owner, repo, prNumber, requiredChecks, timeoutMinutes) {
  const deadline = Date.now() + (timeoutMinutes * 60 * 1000);
  
  while (Date.now() < deadline) {
    const status = await getPRStatus(owner, repo, prNumber);
    
    const allRequiredComplete = requiredChecks.every(required => 
      status.status.some(check => 
        check.name === required && 
        check.status !== "pending"
      )
    );
    
    if (allRequiredComplete) {
      return status;
    }
    
    await new Promise(resolve => setTimeout(resolve, 30000));
  }
  
  throw new Error(`Timeout waiting for checks after ${timeoutMinutes} minutes`);
}

This function polls GitHub every 30 seconds until either all required checks complete or the timeout is reached. Adjust the polling interval based on your typical CI pipeline durations.

Integrating with Claude Code Sessions

To make this truly useful within Claude Code workflows, you can create custom skills that integrate status checking into your development process. Consider creating skills for common scenarios:

Wait for CI: Block until all CI checks pass
Retry failed checks: Automatically trigger re-runs of failed checks
Notify on failure: Send notifications when checks fail
Block on requirement: Only proceed with merges when specific checks pass

Here’s an example skill that waits for PR checks:

name: wait-for-pr-checks
description: Wait for all required PR status checks to complete

Automating PR Merge Conditions

Beyond simple status checking, you can build more sophisticated automation that makes decisions based on PR status. For example, you might want to automatically merge PRs when all checks pass:

async function attemptAutoMerge(owner, repo, prNumber) {
  const { data: pr } = await github.rest.pulls.get({
    owner,
    repo,
    pull_number: prNumber
  });
  
  const { data: combinedStatus } = await github.rest.repos.getCombinedStatusForRef({
    owner,
    repo,
    ref: pr.head.sha
  });
  
  if (combinedStatus.state === "success") {
    await github.rest.pulls.merge({
      owner,
      repo,
      pull_number: prNumber,
      merge_method: "squash"
    });
    return { success: true, message: "PR merged successfully" };
  }
  
  return { 
    success: false, 
    message: `PR not ready for merge, status: ${combinedStatus.state}` 
  };
}

This function first verifies that all statuses are successful before attempting to merge. It uses squash merging, which creates a clean commit history while preserving the PR’s commits in the git history.

Best Practices for PR Status Workflows

When implementing PR status check workflows with Claude Code, keep these best practices in mind:

Always use timeouts: Network issues and CI delays happen. Build reasonable timeouts into any wait operations to prevent workflows from hanging indefinitely.

Handle edge cases: What happens if a required check doesn’t run at all? Your workflow should detect this and report it clearly rather than waiting forever.

Log extensively: Since PR status workflows often run in the background, comprehensive logging helps debug issues when things go wrong.

Respect rate limits: GitHub’s API has rate limits. If you’re checking status frequently, implement exponential backoff to avoid hitting these limits.

Summary

Building PR status check workflows with Claude Code opens up powerful automation possibilities for your development process. From simple status monitoring to sophisticated auto-merge systems, the GitHub API integration allows you to create workflows that fit your team’s specific needs.

Remember to always handle failures gracefully, implement appropriate timeouts, and keep your credentials secure. With these patterns in place, you can create reliable automation that improves your team’s productivity and code quality.

Built by theluckystrike — More at zovo.one