GitHub Apps

By Madis Kõosaar
GitHub GitHub-App Authentication

GitHub Apps

What is a GitHub App

GitHub Apps allow you to automate and improve your workflow. They are the officially recommended way to integrate with GitHub because of the granularity offered in permissions, and while GitHub supports both OAuth apps and GitHub apps, we’ll focus on the latter for this post.

Why use a GitHub App

When integrating with GitHub you rarely want to use a Personal Access Token, and there are a couple of reasons for that

  • It’s insecure. It’s not in all cases you want to grant access to everything and while you can scope the permissions of your token, you’re opening it up to everything your account has access too, with those scoped permissions. An example would be giving the repo contents permission, it would then be able to access all repository contents your account can access.
  • A GitHub App is a first-class actor, meaning it acts on behalf of itself rather than impersonating a user.
  • GitHub Apps allow you to create a granular permission setup where you can scope the permissions but also restrict it to even a single repository, or all the way up to an entire organisation.
  • A GitHub App does not consume a license.

Keep in mind that a GitHub app is not the correct answer for everything, and sometimes an OAuth app or a Personal Access Token may be more appropriate, depending on what you’re trying to do.

How to set up your GitHub App

Apps can be owned by both Organizations and Users, and as such you can create them in two different places. Navigate to the Settings -> Developer Settings -> GitHub Apps, under the appropriate profile and click New GitHub App image

Follow the instructions and fill in all the required fields, note that the homepage url can be anything but it is required to be filled. Then you need to set up a Webhook if you need one for your app, and scope the permissions for you GitHub app. If you don’t need a Webhook, make sure to deactivate it. Finally you need to decide whether you want this app to be publicly available or private and only available on your user/organisation.

And there you go, you’ve set up a GitHub App, now we’ll show you how to use it.

How to use your GitHub App

GitHub Apps can be used for a variety of things, in essence it’s just a different way to authenticate.

Installing your GitHub App

Before we can do anything with the app, we need to install and authorize it to the resources we want to interact with. Navigate to your apps page; Settings -> Developer Settings -> Install App and click Install image

Now the app is installed, we’ll need to fetch access tokens to interact as the app.

Access Tokens and Authentication

In order to request an access token, we’ll need the App ID and a Private Key.

You can find the App id in the same settings page where you installed the App, under General

image

To get a Private Key we can generate it at the bottom of the General tab, note that this will download a .pem file to your machine, which contains the Private Key.

image You can generate your JWT however you want, but here’s a small example from GitHubs official documentation in ruby:


require 'openssl'
require 'jwt'  # https://rubygems.org/gems/jwt


# Private key contents
private_pem = File.read("YOUR_PATH_TO_PEM")
private_key = OpenSSL::PKey::RSA.new(private_pem)


# Generate the JWT
payload = {
  # issued at time, 60 seconds in the past to allow for clock drift
  iat: Time.now.to_i - 60,
  # JWT expiration time (10 minute maximum)
  exp: Time.now.to_i + (10 * 60),
  # GitHub App's identifier
  iss: "YOUR_APP_ID"
}



jwt = JWT.encode(payload, private_key, "RS256")
puts jwt

Note that you have to replace the values YOUR_PATH_TO_PEM and YOUR_APP_ID After creating the JWT, set it in the Header of the API request:

TOKEN=$(ruby PATH_TO_YOUR_RUBY_SCRIPT)

AC=curl -i -X POST -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.github+json" https://api.github.com/app/installations/YOUR_APP_ID/access_tokens
echo $AC

You now have a valid access token for 10 minutes, and will need to request a new access token next time your app interacts with GitHub.

Summary

  • You’ve now seen how to set up a GitHub App
  • You’ve seen how to install the app
  • You’ve seen how to request an access token
  • You know why you should use a GitHub app, and when

This blog post was co-authored with @Mathias Bidstrup