GitHub App Development Skill

GitHub App Development

Build custom GitHub Apps for automation, integrations, and workflow management using best practices for scalable, maintainable applications.

Getting Started

GitHub Apps are first-class integrations that act on their own behalf, providing granular permissions and webhook subscriptions for specific repositories.

Quick wins:

This skill covers:

App registration and authentication
Webhook handling and API integration
Best practices and anti-patterns
Deployment strategies
Security and error handling

This skill does NOT cover:

GitHub Actions development (see github-actions skill)
OAuth apps for user authentication
App marketplace strategy

Quick Reference

App Types

| Type | Acts As | Use Case | |------|---------|----------| | GitHub App | Itself or user | Automation, integrations, bots | | OAuth App | User only | "Sign in with GitHub", user-facing tools |

Authentication

GitHub Apps use a three-tier authentication model:

JWT tokens - Authenticate the app itself (signed with your private key)
Installation tokens - Scoped access to specific repositories (exchanged from JWT)
User tokens - Optional user-delegated permissions (OAuth flow)

Most apps only need installation tokens. See examples/auth-patterns.ts for implementation details.

Authentication Best Practices

Essential security patterns:

Generate fresh JWT tokens (expire in 10 minutes)
Cache and refresh installation tokens (expire in 1 hour)
Scope operations to specific installations
Handle 401/403 errors gracefully

See references/authentication.md for advanced patterns and examples/auth-patterns.ts for implementation examples.

Permission Categories

| Category | Examples | When to Use | |----------|----------|-------------| | Repository | contents, pull_requests, issues | Most apps | | Organization | members, teams | Org-level automation |

See references/permissions.md for complete permission matrix.

Example Use Cases & Configurations

Common App Types with Ready-to-Use Configs

🚀 PR Automation Bot Auto-label PRs, assign reviewers, enforce quality gates

Config: app-configuration.yaml#pr-automation-bot
Implementation: patterns/auto-labeling.ts + patterns/reviewer-assignment.ts
Permissions needed: contents:read, pull_requests:write, issues:write

🔒 Security Scanner Scan for secrets, vulnerabilities, license compliance

Config: app-configuration.yaml#security-scanner-bot
Implementation: webhook-security.ts
Permissions needed: contents:read, security_events:write, vulnerability_alerts:read

📋 Issue Triage Assistant Route issues to teams, auto-label by content

Config: app-configuration.yaml#issue-triage-bot
Implementation: production-app.ts
Permissions needed: issues:write, metadata:read

🚢 Release Manager Generate changelogs, manage releases, close issues

Config: app-configuration.yaml#release-bot
Implementation: production-app.ts
Permissions needed: contents:write, issues:write, pull_requests:read

Framework-Specific Examples

⚡ Cloudflare Workers (Edge-First) Best for: Low latency, global deployment, simple logic

// Minimal viable app in <100 lines
export default { async fetch(request, env) { ... } }

Example: cloudflare-workers-minimal.ts
Deploy guide: deployment/cloudflare-workers.md

🤖 Probot Framework (Rapid Development) Best for: Prototyping, complex logic, multiple integrations

export = (app) => {
  app.on('pull_request.opened', async (context) => { ... })
}

Example: probot-simple.ts
Setup guide: setup-guide.md

☁️ Serverless Functions (Auto-scaling) Best for: Variable load, complex processing, existing infrastructure

AWS Lambda: deployment/aws-lambda.md
Vercel: deployment/vercel.md

Configuration Examples

✅ Best practice examples:

Minimal permissions: app-configuration.yaml#permission-patterns
Complete event coverage: app-configuration.yaml#event-patterns
Security checklist: best-practices.md

Best Practices & Anti-patterns

Essential Best Practices

🔒 Security First

Verify all webhook signatures - Never process unverified webhooks
Request minimal permissions - Use principle of least privilege
Secure secret management - Use dedicated secret managers, not env vars
Validate all inputs - Sanitize webhook payloads and user data

⚡ Performance & Reliability

Acknowledge webhooks quickly - Respond within 30 seconds, process async
Implement circuit breakers - Graceful degradation when GitHub API is slow
Cache installation tokens - Refresh before expiry, batch API calls
Monitor rate limits proactively - Check remaining quota before operations

🏗️ Architecture & Maintainability

Separate concerns - Dedicated modules for auth, webhooks, services
Make operations idempotent - Handle duplicate webhook deliveries gracefully
Use structured logging - Include context (repo, PR number, installation)
Test with realistic payloads - Use actual GitHub webhook examples

See examples/best-practices.md for comprehensive implementation examples and security checklists.

Common Anti-patterns to Avoid

❌ Security Anti-patterns

Skipping signature verification - "Just for development" becomes production

// DON'T: Skip verification
app.post('/webhook', (req, res) => {
  // Process without verifying req.headers['x-hub-signature-256']
})

Over-privileged permissions - Requesting admin when read suffices

# DON'T: Request excessive permissions
permissions:
  administration: write  # Dangerous! Almost never needed
  contents: write        # Do you really need to modify files?

Logging sensitive data - Tokens in error messages or debug logs
Hardcoded secrets - Credentials in source code or config files

❌ Performance Anti-patterns

Synchronous webhook processing - Blocking responses while making API calls
Unbounded API requests - Making 100+ calls without rate limit checks
Memory leaks in long-running apps - Not cleaning up event listeners
Missing error boundaries - One failed operation breaks entire workflow

❌ Integration Anti-patterns

Polling instead of webhooks - Inefficient API usage patterns
Not handling app uninstalls - Continuing to process events after removal
Ignoring GitHub API deprecations - Using outdated endpoints or parameters
Assuming webhook order - Events may arrive out of sequence

Under-configured webhooks - Missing critical events for your use case

# DON'T: Miss critical events for PR bot
events: [issues]  # Forgot pull_request events!

Framework Selection Guidelines

| Scale | Complexity | Recommended Approach | When to Use | |-------|------------|---------------------|-------------| | Small (< 100 repos) | Simple automation | Probot | Learning, prototyping, simple bots | | Medium (100-1000 repos) | Custom logic | Hono + Octokit | Production apps, edge deployment | | Large (1000+ repos) | Enterprise features | Custom framework | Event streaming, multi-tenant |

See references/implementation-patterns.md for detailed architecture guidance and references/anti-patterns.md for comprehensive anti-pattern examples and recovery strategies.

Error Handling & Rate Limiting

Quick Error Response Guide

Key error handling patterns:

403 (Rate Limited): Wait for reset time, implement backoff
5xx (Server Errors): Retry with exponential backoff
401/403: Check credentials/permissions, refresh tokens
400/404: Validate request parameters, verify resource exists

Rate Limit Essentials

Key principles:

Monitor usage before hitting limits
Implement graceful degradation strategies
Use exponential backoff for retries

See examples/webhook-security.ts for rate limit monitoring implementation and references/error-handling.md for comprehensive patterns.

Observability & Monitoring

Essential Monitoring Targets

Application health: Response times, error rates, resource usage GitHub API integration: Rate limits, authentication failures, API errors Business metrics: Installations, active repositories, feature usage

Quick OpenTelemetry Setup

Key trace targets for GitHub Apps:

webhook.{event_type} - Processing time and errors
github.api.{operation} - API performance and rate limits
auth.installation_token - Authentication overhead

See references/observability.md for complete OpenTelemetry setup, alerting strategies, health checks, and dashboard configurations.

Architecture & Patterns

Framework Decision Matrix

| Scale | Framework | Architecture | |-------|-----------|-------------| | Small (< 100 repos) | Probot | Single instance, simple | | Medium (100-1000 repos) | Probot or Hono | Load balanced, cached | | Large (1000+ repos) | Custom Octokit | Event streaming, queues |

Core Design Principles

✅ Essential patterns:

Event-driven architecture with dedicated handlers
Stateless operations (no in-memory state)
Background processing for heavy operations
Idempotent webhook handling

❌ Avoid these anti-patterns:

Monolithic webhook handlers processing all events
Synchronous processing of heavy operations
Direct database access from webhook handlers

See references/probot.md for framework comparisons and references/hosting/ for platform-specific patterns.

Testing & Quality

Test Strategy Overview

Follow the 70/20/10 test pyramid:

70% Unit Tests - Business logic and utilities
20% Integration Tests - Webhook processing with mocked API
10% End-to-End Tests - Full flow with test repositories

Critical Test Scenarios

Authentication: Token expiration, app uninstalls, permission changes Webhooks: Duplicate delivery, signature verification, malformed payloads Rate limits: Graceful degradation, retry logic, secondary limits

See references/testing.md for complete testing frameworks, patterns, and automation strategies.

Production Deployment

Pre-deploy Checklist

Security essentials:

Webhook signature verification enabled
Private key in secure vault (not env vars)
Minimum required permissions only

Reliability essentials:

Health checks responding
Error monitoring configured
Response times < 10s (GitHub timeout)

Configuration

Required environment variables:

GITHUB_APP_ID - Your app's unique identifier
GITHUB_PRIVATE_KEY - App authentication key
GITHUB_WEBHOOK_SECRET - Webhook signature verification

See references/hosting/ for platform-specific deployment guides and examples/deployment/ for complete configuration examples.

Performance & Optimization

Critical Performance Targets

Response times: Acknowledge webhooks within 30 seconds Async processing: Queue non-critical operations Resource management: Stream large payloads, monitor memory

Common Bottlenecks

Avoid these performance killers:

Synchronous GitHub API calls in webhook handlers
Database queries blocking webhook responses
Loading large payloads into memory
CPU-intensive tasks blocking the main thread

See references/observability.md for detailed performance monitoring and optimization strategies.

Implementation Guides

Quick Setup (15 minutes)

Register app - GitHub Settings → Developer settings → GitHub Apps
Choose framework - Probot for rapid development, raw Octokit for Workers
Deploy - Start with examples, customize for your needs

See examples/README.md for step-by-step setup guides.

Development Workflow

Three-phase approach:

Setup - Register app, configure permissions, download key
Development - Clone templates, implement handlers, test locally
Deployment - Configure secrets, deploy, install on repos

See examples/setup-guide.md for detailed step-by-step instructions.

Advanced Configuration Examples

🏢 Enterprise Apps - Multi-tenant, organization-scoped with SAML/SSO integration 🔄 Multi-Repository Orchestration - Coordinate changes across multiple repositories 📊 Analytics & Reporting - Read-only apps that collect metrics without making changes

See references/advanced-configuration.md for complete enterprise patterns, deployment scenarios by scale, and configuration examples.

Integration Examples

Connect GitHub Apps with external systems using proven integration patterns:

🔗 External API Integration - Slack, Jira, CI/CD systems 📝 Custom Workflow Automation - Repository-specific business logic 🔐 Security Integration - Automated security scanning and policies

See references/integration-patterns.md for implementation details, authentication patterns, and resilience strategies.

Common Implementation Patterns

Essential App Patterns

Auto-labeling - Label PRs based on conventional commit titles Reviewer assignment - Route to team members based on file paths Quality gates - Enforce checks based on repository settings Welcome automation - Greet first-time contributors Configuration-based logic - Use repository properties for behavior

See references/implementation-patterns.md for complete code examples, event processing patterns, and state management strategies.

Hosting Platforms

Choose the right platform based on your scale and requirements. See references/hosting/ for detailed deployment guides and platform comparisons.

API Reference

Core Operations

Essential API categories:

Pull Requests - Reviews, comments, status updates
Issues & Comments - Create, label, assign, respond
Checks & Status - CI integration, status reporting
Repository - Files, branches, webhooks, settings

See references/octokit.md for complete API reference and examples/production-app.ts for real-world usage patterns.

Webhook Events

Most common events:

pull_request.opened - New PR created
issues.opened - New issue created
issue_comment.created - Comment added
check_run.completed - CI check finished

See references/webhooks.md for complete event reference.

Security & Operations

Security Checklist

✅ Essential security measures:

Verify webhook signatures before processing
Request minimum necessary permissions
Store private key securely (use secrets manager)
Validate all webhook payload input
Use HTTPS for all communication

Common Issues

Authentication problems:

Check private key format (PEM) and app ID
Verify token hasn't expired
Confirm app is installed on target repository

Webhook delivery issues:

Verify webhook URL is accessible
Check webhook secret matches
Confirm app subscribes to necessary events

See references/error-handling.md for detailed troubleshooting guides.

Agent Skills: GitHub App Development

Install this agent skill to your local

Skill Files