🤖 GitHub Apps Cheat Sheet ✨

A cheat sheet for GitHub Apps...

Contents

• Key concepts
• Creating your first GitHub App
• Resources
• Notable APIs for GitHub Apps
• Tools
• Best practices

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

• Building GitHub Apps
• GitHub Developer Documentation
• GitHub REST and GraphQL APIs
• Migrating OAuth Apps to GitHub Apps

Notable APIs for GitHub Apps

• GitHub App information
  • Get the authenticated GitHub App (JWT)
• Identify installation information
  • List installations (JWT)
  • Get an organization installation (JWT)
  • Get a user installation (JWT)
• Token creation / revocation
  • Create a new installation token (JWT)
  • Revoke an installation token (installation access token)
• Identify installation resources
  • List repositories (installation access token)
• Identify user-accessible resources
  • List installations for a user (user-to-server OAuth access token)
  • List repositories accessible to the user for an installation (user-to-server OAuth access token)

Tools

• Octokit libraries
• apptokit a CLI for working with GitHub Apps, built by one of the GitHub Apps Engineers
• github-apps-helper plugin for Insomnia
• API route specifications for Insomnia
• Probot a Node.js framework for building GitHub Apps
• smee.io a webhook payload delivery service
• smee-client a client for receiving webhook payloads locally via smee.io
• jsonwebtokenydoo a command line utility to assist with GitHub App authentication
• jwt-cli a command line utility to assist with JWT creation

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