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

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:

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

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)

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