Jekyll Auth

Getting Started

Create a GitHub Application

  1. Navigate to the GitHub app registration page
  2. Give your app a name
  3. Tell GitHub the URL you want the app to eventually live at. If using a free Heroku account, this will be something like http://my-site.herokuapp.com
  4. Specify the callback URL; should be like this: https://my-site.herokuapp.com/auth/github/callback; note that this is https, not http.
  5. Hit Save, but leave the page open, you’ll need some of the information in a moment

Remember the ‘my-site’ part for later on when using heroku create. Also, my-site is often called ‘app-name’ in Heroku documentation.

Add Jekyll Auth to your site

  1. Within your new site repository or orphaned github branch (the branch could be named anything except ‘gh-pages’ since this would then be public on GitHub!), add gem 'jekyll-auth' to your Gemfile or if you don’t already have a Gemfile, create a file called Gemfile in the root of your site’s repository with the following content:

    source "https://rubygems.org"

gem 'jekyll-auth'

  2. cd into your project’s directory and run bundle install. If you get an error using bundle install, see Troubleshooting below.

  3. Run bundle exec jekyll-auth new which will copy the necessary files to set up the server

Setting up hosting with Heroku

Automatically

Run bundle exec jekyll-auth setup --client_id XXX --client_secret XXX --org_name XXX

(or --team_id XXX)

Manually

  1. You may need to add and commit the files generated by jekyll-auth new to Git before continuing
  2. Make sure you have the Heroku toolbelt installed
  3. Run heroku create my-site from your site’s directory; make sure my-site matches what you specified in the GitHub application registration above.
  4. heroku config:set GITHUB_CLIENT_ID=XXX GITHUB_CLIENT_SECRET=XXX GITHUB_ORG_NAME=XXX (or GITHUB_TEAM_ID)
  5. git push heroku, or if you are maintaining the site in an orphaned branch of your GitHub repo (say ‘heroku-pages’), do git push heroku heroku-pages:master
  6. heroku open to open the site in your browser

Find the Organization ID (needed to find Team ID)

If you need to find an organization’s ID, you can use the following cURL command:

curl https://api.github.com/orgs/{org_name}

Finding the Team ID

If you need help finding a team’s numeric ID, you can use the jekyll-auth team_id command.

For example, to find the team ID for @jekyll/maintainers you’d run the command:

jekyll-auth team_id --org jekyll --team maintainers

You’ll want to add a personal access token to your .env file so that Jekyll-Auth can make the necessary API request, but the command will run you through the process if you do not provide this.