Repository files navigation

A cheat sheet for GitHub Apps...

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

• 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 throughinstallations
  • Are supported by GitHub.comand 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 theinstallation token, orinstallation access token) Permits access to resources within the scope of an installation, expires after one hour, created viathe REST API
  • User-to-server token: Permits access to resources that are visible toboth an end-userand 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 asignature to GitHub.com to confirm to GitHub that we are the App we are claiming to be

1. Navigate to GitHub Apps from yourGitHub 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!

• Building GitHub Apps
• GitHub Developer Documentation
• GitHubREST andGraphQL APIs
• Migrating OAuth Apps to 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)

• Octokit libraries
• apptokit a CLI for working with GitHub Apps, built by one of the GitHub Apps Engineers
• github-apps-helper plugin forInsomnia
• API route specifications forInsomnia
• 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 viasmee.io
• jsonwebtokenydoo a command line utility to assist with GitHub App authentication
• jwt-cli a command line utility to assist with JWT creation

Do:

• ✅ Usewebhooks to ingest data
• ✅ Cache and re-use server-to-server (installation access tokens) as much as possible
• ✅ Useconditional requests wherever possible
• ✅ Retry requests when handling "fresh" data
• ✅ Include a descriptiveUser-Agent header in your API requests
• ✅ Save theX-GitHub-Request-Id response header value, especially for error (4xx, 5xx) responses
• ✅ Subscribe tothis RSS feed for Platform updates
• ✅ Consider listing your GitHub App onGitHub Marketplace
• ✅ Consider other best practices listedhere

Don't:

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