/github-apps-cheat-sheet

A cheat sheet for GitHub Apps

Creative Commons Zero v1.0 UniversalCC0-1.0

🤖 GitHub Apps Cheat Sheet ✨

A cheat sheet for GitHub Apps...

Contents

Key concepts

  • GitHub Apps

    • Offer a secure way for third parties to programmatically access protected resources on GitHub
    • Are a first-class actor on GitHub -- acting independently of resource owners (GitHub users and organizations)
    • Have a fine-grained permissions model -- customers are able to more confidently grant third parties access to their protected resources
    • Have dedicated rate limits, that scale with the app's usage
    • Facilitate webhook event consumption
    • Follow a repo-centric permissions model through installations
    • Are supported by GitHub.com and GitHub Enterprise Server
  • Other key terms:

    • Installation: Connects a GitHub App to one or more repositories owned by an organization or user
    • Permissions: Dictate what an App can see, or do in the context of an installation
    • Webhooks: Dictate what events an App will be notified about, over a single HTTP endpoint, registered with the GitHub App
    • Server-to-server token: (Also commonly referred to as the installation token, or installation access token) Permits access to resources within the scope of an installation, expires after one hour, created via the REST API
    • User-to-server token: Permits access to resources that are visible to both an end-user and the GitHub App, acquired through an OAuth-like flow
    • JWT: (JSON Web Tokens) an open web standard, allowing for information to be securely transmitted between two parties as a JSON object, in this context, JWTs are used to securely transmit a signature to GitHub.com to confirm to GitHub that we are the App we are claiming to be

Creating your first GitHub App

  1. Navigate to GitHub Apps from your GitHub Developer Settings
  2. Register a New GitHub App, setting up URLs, permissions, and events
  3. Download the private key and App ID and start coding!

Resources

Notable APIs for GitHub Apps

Tools

Best practices

Do:

  • ✅ Use webhooks to ingest data
  • ✅ Cache and re-use server-to-server (installation access tokens) as much as possible
  • ✅ Use conditional requests wherever possible
  • ✅ Retry requests when handling "fresh" data
  • ✅ Include a descriptive User-Agent header in your API requests
  • ✅ Save the X-GitHub-Request-Id response header value, especially for error (4xx, 5xx) responses
  • ✅ Subscribe to this RSS feed for Platform updates
  • ✅ Consider listing your GitHub App on GitHub Marketplace
  • ✅ Consider other best practices listed here

Don't:

  • ❌ Depend on concurrent requests, this can trigger secondary rate limits
  • ❌ Poll, use webhooks where possible