Awesome Open Source
Awesome Open Source


A tiny microservice that makes adding authentication with GitHub to your application easy.


Running your own micro-github is a single now command away:

# Deploy this repository using
now mxstbr/micro-github -e GH_CLIENT_ID=xyz123 -e GH_CLIENT_SECRET=asdf123 -e REDIRECT_URL=

Environment variables

You'll need to provide three environment variables when running micro-github:

# Your GitHub application client id
# Your GitHub application client secret
# The URL to redirect the user to once the authentication was successful
# Optional: Specify the GitHub host when using GitHub Enterprise

Create an application on GitHub here to get your client id and secret if you haven't done that already.

When authentication is successful, the user will be redirected to the REDIRECT_URL with the access_token query param set to the GitHub access token. You can then use that token to interact with the GitHub API!

E.g. setting REDIRECT_URL= will redirect them to (where asdf123 is the provided access token)

Finish setup

To make this work you have to set the authorization callback URL of your application on GitHub to whatever URL now gave you plus the path /callback e.g. http://localhost:3000/callback:

Authorization callback URL: ''

To log people in provide a link to url now gave you plus the path login e.g. http://localhost:3000/login when they click on the link it will redirect to (where client_id is your GitHub app client id in .env and state is a randomly generated string). This will redirect them to the GitHub sign in page for your app, which looks like this:

Authorize my app to access your data on GitHub

You can change the scope of the data you can access with the scope query param, see the GitHub docs!

When authentication is successful, the user will be redirected to the REDIRECT_URL with the access token from GitHub for you to use! 🎉

Error handling

In case an error happens (either by the service or on GitHub) the user will be redirected to the REDIRECT_URL with the error query param set to a relevant error message.


git clone [email protected]:mxstbr/micro-github.git

Move .env.example to .env and fill in your GitHub API details and redirect url

npm run dev

The server will then be listening at localhost:3000, so set the authorization callback URL of your dev application on GitHub to http://localhost:3000/callback.


The master branch of this repository is what you will be deploying. To update to a new version with potential bugfixes, all you have to do is run the now command again and then set the authorization callback URL on GitHub to the new URL that now gave you! 👌


Copyright (c) 2017 Maximilian Stoiber, licensed under the MIT license. See for more information.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (70,402
nodejs (3,806
github (753
microservices (463
github-api (137
micro (57