README

Stop context-switching between PRs. Start automating approvals, merges, and bulk operations.

Approve, merge, request changes, and manage pull requests at scale with expressive PHP code. Built for teams shipping multiple releases per day.

Installation

composer require conduit-ui/pr

Why This Exists

Your team merges 30+ PRs per day. You're manually checking CI status, approving dependency updates, and enforcing review policies. This package automates the repetitive parts so your team can focus on code review that matters.

Quick Start

use ConduitUI\Pr\PullRequest;

// Approve and merge a PR
PullRequest::find('owner/repo', 123)
    ->approve('LGTM! Shipping it.')
    ->merge();

// Auto-merge all passing Dependabot PRs
PullRequest::query('owner/repo')
    ->author('dependabot[bot]')
    ->open()
    ->get()
    ->filter(fn($pr) => $pr->checksPass())
    ->each(fn($pr) => $pr->merge());

Core Features

Review Actions

Approve PRs

PullRequest::find('owner/repo', 456)
    ->approve('Great work! Tests look good.');

Request Changes

PullRequest::find('owner/repo', 789)
    ->requestChanges('Please add tests for the new feature.');

Add Review Comments

PullRequest::find('owner/repo', 101)
    ->comment('Consider extracting this logic into a separate class.');

Inline Code Comments

PullRequest::find('owner/repo', 202)
    ->addInlineComment(
        path: 'src/Service.php',
        line: 42,
        comment: 'This could cause a race condition'
    );

Merge Operations

Simple Merge

$pr = PullRequest::find('owner/repo', 123);
$pr->merge(); // Merge commit (default)

Merge Strategies

$pr->merge(strategy: 'squash'); // Squash and merge
$pr->merge(strategy: 'rebase'); // Rebase and merge

Conditional Merge

$pr = PullRequest::find('owner/repo', 123);

if ($pr->checksPass() && $pr->approved()) {
    $pr->merge();
}

State Management

Close & Reopen

// Close without merging
$pr->close();

// Reopen a closed PR
$pr->reopen();

Advanced Queries

Filter by State

PullRequest::query('owner/repo')
    ->state('open')
    ->get();

Filter by Author

PullRequest::query('owner/repo')
    ->author('username')
    ->get();

Filter by Labels

PullRequest::query('owner/repo')
    ->labels(['ready-to-merge', 'hotfix'])
    ->get();

Sort Results

PullRequest::query('owner/repo')
    ->sort('created', 'desc')
    ->get();

Convenience Methods

// All open PRs
PullRequest::query('owner/repo')->open()->get();

// All closed PRs
PullRequest::query('owner/repo')->closed()->get();

// All merged PRs
PullRequest::query('owner/repo')->merged()->get();

Real-World Automation

Auto-Merge Dependabot

// Run this on a schedule (every 15 minutes)
PullRequest::query('owner/repo')
    ->author('dependabot[bot]')
    ->open()
    ->get()
    ->filter(fn($pr) => $pr->checksPass())
    ->filter(fn($pr) => $pr->title->contains(['patch', 'minor']))
    ->each(function($pr) {
        $pr->approve('Auto-approving passing dependency update');
        $pr->merge(strategy: 'squash');
    });

Enforce Review Policy

// Block merge if not approved by 2+ reviewers
$pr = PullRequest::find('owner/repo', 123);

if ($pr->approvals()->count() < 2) {
    $pr->comment('⚠️ This PR requires 2 approvals before merging.');
    exit(1);
}

Bulk Label Management

// Add "shipped" label to all merged PRs from this week
PullRequest::query('owner/repo')
    ->merged()
    ->since(now()->startOfWeek())
    ->get()
    ->each(fn($pr) => $pr->addLabels(['shipped']));

Hotfix Fast-Track

// Auto-merge hotfixes that pass CI
PullRequest::query('owner/repo')
    ->label('hotfix')
    ->open()
    ->get()
    ->filter(fn($pr) => $pr->checksPass())
    ->each(function($pr) {
        $pr->approve('Hotfix approved via automation');
        $pr->merge(strategy: 'squash');
    });

Usage Patterns

Static API (Recommended)

use ConduitUI\Pr\PullRequest;

$pr = PullRequest::find('owner/repo', 123);
$prs = PullRequest::query('owner/repo')->open()->get();

Instance API

use ConduitUI\Pr\PullRequestManager;

$manager = new PullRequestManager('owner/repo');
$pr = $manager->find(123);
$prs = $manager->query()->open()->get();

Data Objects

All responses return strongly-typed DTOs:

$pr->id;              // int
$pr->number;          // int
$pr->title;           // string
$pr->state;           // 'open' | 'closed' | 'merged'
$pr->author;          // User object
$pr->reviewers;       // Collection of User objects
$pr->labels;          // Collection of Label objects
$pr->headBranch;      // string
$pr->baseBranch;      // string
$pr->mergeable;       // bool
$pr->createdAt;       // Carbon instance
$pr->updatedAt;       // Carbon instance
$pr->mergedAt;        // ?Carbon instance
$pr->checksPass();    // bool - All CI checks passing
$pr->approved();      // bool - Has approvals
$pr->approvals();     // Collection of Review objects

Configuration

Publish the config file:

php artisan vendor:publish --tag="pr-config"

Set your GitHub token in .env:

GITHUB_TOKEN=your-github-token

Requirements

• PHP 8.2+
• GitHub personal access token with repo scope

Testing

composer test

Code Quality

composer format  # Fix code style
composer analyse # Run static analysis

Related Packages

• conduit-ui/issue - Issue triage automation
• conduit-ui/repo - Repository governance
• conduit-ui/connector - GitHub API transport layer

Enterprise Support

Automating PR workflows across your organization? Contact jordan@partridge.rocks for custom solutions including compliance checks, advanced approval rules, and audit logging.

License

MIT License. See LICENSE for details.