GitHub is where developer work happens. Issues, pull requests, code review, releases — the entire software development lifecycle runs through it. An AI agent that understands your GitHub activity can meaningfully reduce the overhead of project management and code review.
This guide covers the complete OpenClaw-GitHub integration: auth (the right way), webhook subscriptions, issue auto-triage and auto-labeling, PR automation, and a safety section on what AI should and absolutely should not do with your codebase.
Auth: Personal Access Token vs. GitHub App
This is the most important decision in the setup. Use the wrong auth method and you’ll either hit rate limits, lack necessary permissions, or create security issues.
Personal Access Token (PAT)
A PAT is a credential tied to your personal GitHub account. Simple to create, works immediately, commonly used.
The problem: PATs act as you. Every action OpenClaw takes — commenting on PRs, adding labels, creating issues — appears as coming from your personal account. And fine-grained PATs expire (90 days max for fine-grained; classic PATs can be set to no expiry but that’s a security antipattern).
When PATs are appropriate:
- Personal repos only
- Solo projects where you don’t mind actions appearing under your account
- Quick prototyping
Generate a fine-grained PAT:
- GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
- Set repository access to specific repos or “All repositories”
- Set permissions:
- Issues: Read and write
- Pull requests: Read and write
- Contents: Read (for reading code context)
- Metadata: Read
- Commit statuses: Read and write (if you want CI status)
- Set expiration (90 days max)
- Generate and copy
GITHUB_TOKEN="github_pat_xxxx..."
GitHub App (Use This Instead)
A GitHub App is a first-class integration — separate from any user account, with its own identity, fine-grained permissions, and webhook handling built in.
Why GitHub App is better:
- Actions appear as “[YourApp] · GitHub App” not your personal account
- No expiry headaches — apps use short-lived installation tokens (1 hour) generated from a private key
- Installable on multiple repos or organizations without tying to a personal account
- Better rate limits: 5,000 requests/hour per installation vs. 5,000/hour per user
- Proper webhook support with shared secret validation
Create a GitHub App:
- GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
- Name it “OpenClaw – [YourName]”
- Homepage URL: anything (can be your paioclaw.ai profile)
- Webhook URL: your OpenClaw server endpoint (or PaioClaw’s webhook URL)
- Webhook secret: generate a random 32+ character string
- Permissions:
- Issues: Read and write
- Pull requests: Read and write
- Contents: Read-only
- Commit statuses: Read and write
- Metadata: Read-only
- Subscribe to events: Issues, Pull requests, Issue comments, Pull request reviews, Push (optional)
- Create the App
- Generate and download the private key (.pem file)
Install the App:
After creation, go to your App page → Install App → Install on your account or organization → Select repositories.
OpenClaw config:
github_app:
app_id: "123456"
private_key_path: "/path/to/private-key.pem"
installation_id: "78901234" # Found in: GitHub App settings → Installations
OpenClaw generates short-lived installation tokens automatically when making API calls. You don’t manage token refresh manually.
Setting Up Webhook Subscriptions
Webhooks are what make the GitHub integration reactive rather than polling-based. GitHub’s webhook delivery is reliable — unlike Jira, GitHub retries failed deliveries and gives you delivery logs.
What Events to Subscribe To
Be selective. Every event you subscribe to generates HTTP traffic and requires processing. Unnecessary events add noise.
For issue automation:
issues— created, edited, labeled, assigned, closedissue_comment— created
For PR automation:
pull_request— opened, closed, merged, review_requestedpull_request_review— submittedpull_request_review_comment— created
For code-related automation:
push— commits pushed (use sparingly; high volume on active repos)check_suite,check_run— CI status
Skip:
star,fork,watch— noise with no action valuepublic— almost never useful in automationsdeployment_status— useful if you track deployments, otherwise skip
Validating Webhook Signatures
Always validate that incoming webhooks are actually from GitHub. GitHub signs every payload with HMAC-SHA256 using your webhook secret.
import hmac
import hashlib
def validate_signature(payload_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode('utf-8'),
payload_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)
The signature comes in the X-Hub-Signature-256 header. If validation fails, reject the request — never process unsigned webhooks.
Issue Auto-Triage and Auto-Labeling
The Triage Recipe
@openclaw triage new issues in github.com/org/repo from the last 24 hours
For each new issue, OpenClaw:
- Reads title and body
- Classifies issue type: bug, feature request, question, documentation, security
- Applies appropriate labels
- Sets an initial response comment for issues that need clarification
- Assigns to team members based on file paths mentioned or component keywords
Auto-label configuration:
github_triage_rules:
bug:
keywords: ["crash", "error", "exception", "broken", "fails", "not working", "regression"]
labels: ["bug"]
priority: ["high-priority"] # if keywords also include "production", "critical"
security:
keywords: ["CVE", "vulnerability", "injection", "bypass", "exposed", "credentials"]
labels: ["security", "high-priority"]
assign: "[email protected]"
feature:
keywords: ["add", "support for", "would be nice", "request", "enhance", "improve"]
labels: ["enhancement"]
question:
keywords: ["how to", "how do I", "what is", "can I", "possible to"]
labels: ["question"]
Welcome Comment for New Issues
For issues that lack reproduction steps (common for bugs), OpenClaw can automatically request them:
@openclaw when a bug issue is created without reproduction steps, ask for them
OpenClaw detects bug issues with no numbered list or “steps to reproduce” section and posts:
Thanks for filing this bug report! To help us diagnose and fix this faster, could you add:
1. Steps to reproduce the issue
2. Expected behavior
3. Actual behavior
4. Your environment (OS, browser, version)
This helps the team prioritize and investigate efficiently.
This is polite, non-spammy, and genuinely improves issue quality. Configure it to only trigger when the issue body is under 200 characters (a good indicator of an incomplete report).
Stale Issue Management
@openclaw check for stale issues in github.com/org/repo — issues with no activity for 60 days
OpenClaw:
- Finds issues unchanged for 60+ days
- Posts a comment: “This issue has been quiet for a while — is it still relevant? We’ll close it in 14 days without activity.”
- Adds a
stalelabel - Closes issues that hit 74 days without activity (60 day warning + 14 day wait)
This is the behavior of the GitHub Stale Action, replicated via OpenClaw with more control over messaging.
PR Automation
Auto-Labeling PRs by Size
pr_size_labels:
xs: { max_lines: 10, label: "size: XS" }
s: { max_lines: 50, label: "size: S" }
m: { max_lines: 200, label: "size: M" }
l: { max_lines: 500, label: "size: L" }
xl: { min_lines: 501, label: "size: XL", comment: "This PR is large. Consider breaking it into smaller PRs for easier review." }
@openclaw when a PR is opened, label it by size
PR Summary Comments
When a PR is opened, OpenClaw can post a structured summary:
@openclaw summarize what this PR does when it's opened: [PR context]
OpenClaw reads the PR diff, title, and description, then posts:
## PR Summary (AI-generated)
**What this changes:** Refactors the authentication middleware to support OAuth 2.0 in addition to API key auth.
**Files changed:** 7 files (314 additions, 89 deletions)
- `src/middleware/auth.ts` — Core auth logic refactored
- `src/routes/oauth.ts` — New OAuth callback handler
- `tests/auth.test.ts` — New test coverage
**Things reviewers should focus on:**
- The token refresh logic in auth.ts (lines 89-124)
- Error handling for expired OAuth tokens
- New test coverage is present but may need edge cases
*Auto-generated by OpenClaw. Review may be incomplete.*
The disclaimer is important. Make it clear this is AI-generated. Don’t let it appear authoritative.
Linking PRs to Issues
When a PR references an issue (via “Fixes #123” or “Closes #456”), GitHub handles the link automatically. But for PRs that address issues without explicit linking:
@openclaw link this PR to the relevant issue if one exists
OpenClaw searches open issues for content similar to the PR’s purpose and suggests the link. You approve before it’s added. Never automate the suggestion without human confirmation — wrong issue links cause confusion during planning.
Review Assignment
@openclaw when a PR touches payments code, request review from the payments team
Configure ownership patterns:
auto_review_assignment:
- paths: ["src/payments/**", "src/billing/**"]
reviewers: ["payments-lead", "billing-engineer"]
- paths: ["src/auth/**", "src/security/**"]
reviewers: ["security-lead"]
- paths: ["infrastructure/**", "*.dockerfile", "docker-compose*"]
reviewers: ["devops-lead"]
AI Code Review: What It Should and Should Not Do
This section deserves its own attention because AI code review is where well-intentioned automation can go wrong.
What AI Code Review Is Good For
Style and convention checking:
@openclaw check this PR for our coding conventions
OpenClaw can detect:
- Missing error handling patterns
- Inconsistent naming conventions (camelCase vs snake_case mixed)
- Console.log statements left in production code
- Commented-out code blocks
- Missing JSDoc on exported functions
These are objective, low-risk observations.
Documentation completeness:
- New public functions without docstrings
- Changed function signatures with outdated docs
- New API endpoints without README updates
Obvious bugs:
- Off-by-one errors in loops
- Null checks missing on potentially null values
- Incorrect use of async/await
What AI Code Review Should NOT Do
Do not auto-approve PRs. Ever.
No matter how confident the AI seems, a human must approve. Period.
Do not auto-merge. Ever.
# This configuration should never exist
github_automation:
auto_merge_on_approval: true # ❌ NEVER
auto_merge_on_ci_pass: true # ❌ NEVER
Auto-merge, even when all CI checks pass, removes human judgment from a critical decision point. A green CI suite doesn’t mean the code does what the PR claims, is safe to deploy, or doesn’t break something the tests don’t cover.
Do not post code suggestions as if they’re required changes:
AI code review comments should be clearly marked as suggestions, not requirements:
? Suggestion (not required): Consider using `Array.from()` here instead of spread syntax —
it's more explicit when converting iterables. Not blocking, just a style note.
The labeling matters. “Consider” and “Suggestion” signal advisory; “Should” and “Must” signal blocking. Use the right language.
Do not review security-critical changes without human security review:
If a PR touches auth, cryptography, payment processing, or data access controls, AI review is supplementary at best. Flag these PRs for mandatory human security review.
A Practical Code Review Recipe
@openclaw review the PR at github.com/org/repo/pull/847 for obvious issues
OpenClaw:
- Reads the diff
- Checks for the objective issues listed above (style, missing error handling, etc.)
- Posts a comment with findings, clearly labeled as AI-generated
- Does NOT request changes — posts as a regular comment
- Does NOT approve the PR
## ? OpenClaw Code Review
Reviewed 7 changed files. Here's what I found:
**Findings (3 items):**
1. `src/auth.ts` line 94: Missing null check on `user.email` before passing to `sendVerificationEmail()`.
If `user.email` is undefined, this will throw.
2. `src/routes/oauth.ts` line 31: `console.log(tokens)` — this logs OAuth tokens to console.
Remove before merging.
3. `tests/auth.test.ts`: New OAuth callback handler has no error case tests.
Consider adding tests for expired code and invalid state parameter.
**No blocking issues found.** Human review recommended before merging.
*This is an AI review. It may miss issues or flag false positives. Not a substitute for human code review.*
That disclaimer at the bottom is non-negotiable.
Rate Limits
GitHub’s rate limits:
- Authenticated requests: 5,000/hour (PAT or GitHub App installation token)
- GitHub App with OAuth token: 5,000/hour per user
- Search API: 30 requests/minute
For most automation, 5,000 requests/hour is more than enough. Where it gets tight: repos with very high PR velocity where you’re reading diffs for every PR. A single PR diff can require multiple API calls (patch endpoint + individual file contents).
Monitor rate limit headers:
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4723
X-RateLimit-Reset: 1716144000
When X-RateLimit-Remaining drops below 500, OpenClaw throttles automatically.
GitHub vs. PaioClaw: Where It Makes Sense
Self-hosting works cleanly for single-repo or single-organization setups. The friction points:
Webhook receiver: You need a public HTTPS endpoint to receive GitHub webhooks. Self-hosting requires a server with a domain and TLS certificate. PaioClaw provides the webhook receiver endpoint, and your OpenClaw instance polls PaioClaw for queued events.
Private key management: GitHub App private keys need to be stored securely. Exposing them in environment variables on a shared server is a security risk. PaioClaw encrypts and manages App credentials.
Multi-org setups: If you contribute to multiple GitHub organizations and want unified automation across them, managing multiple GitHub App installations from self-hosted OpenClaw is genuinely complex. PaioClaw handles multi-installation routing.
Plans start free, Smart at $15/mo, Genius at $25/mo.
Summary
The setup order that works: create a GitHub App (not a PAT), install it on your repos, configure webhook subscriptions with signature validation, then build automations incrementally.
Start with issue triage and auto-labeling — high value, low risk. Add PR size labels and the summary comment next. Build toward code review assistance last, and when you do, maintain strict guardrails: AI reviews are advisory, never blocking; AI never approves or merges; security-critical PRs always get human review.
The “don’t auto-merge” rule is worth writing somewhere visible. It’s the one automation instinct that, if followed, would have prevented a lot of production incidents.