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:

• •Create your first app in 15 minutes
• •Deploy to Cloudflare Workers
• •Use Probot for rapid development

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

Authentication

GitHub Apps use a three-tier authentication model:

1. •JWT tokens - Authenticate the app itself (signed with your private key)
2. •Installation tokens - Scoped access to specific repositories (exchanged from JWT)
3. •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

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
  typescript

  // 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
  yaml

  # 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
  yaml

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

Framework Selection Guidelines

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

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)

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

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

Development Workflow

Three-phase approach:

1. •Setup - Register app, configure permissions, download key
2. •Development - Clone templates, implement handlers, test locally
3. •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.

See Also

• •examples/README.md - Complete starter projects and runnable code samples
• •examples/best-practices.md - Comprehensive implementation examples and security checklists
• •references/anti-patterns.md - Common mistakes and recovery strategies
• •references/testing.md - Comprehensive testing strategies and patterns
• •references/error-handling.md - Advanced error handling and rate limit management
• •references/observability.md - OpenTelemetry setup and monitoring best practices
• •references/webhooks.md - Complete webhook event reference
• •references/permissions.md - Permission matrix and runtime validation
• •references/octokit.md - Octokit SDK patterns
• •cloudflare-workers skill - Detailed CF Workers patterns
• •github-actions skill - Building custom Actions (different from Apps)

External Resources

• •GitHub Apps Documentation
• •Octokit.js
• •Probot
• •GitHub Webhooks