Bunto Auth
A simple way to use GitHub OAuth to serve a protected Bunto site to your GitHub organization

The problem
Bunto and GitHub Pages are awesome, right? Static site, lightning fast, everything versioned in Git. What else could you ask for?
But what if you only want to share that site with a select number of people? Before, you were SOL. Now, simply host the site on a free, Heroku Dyno, and whenever someone tries to access it, it will Oauth them against GitHub, and make sure they're a member of your Organization. Pretty cool, huh?
Requirements
- A GitHub account (one per user)
- A GitHub Organization (of which members will have access to the Bunto site)
- A GitHub Application (you can register one for free)
- A Heroku account (you can technically use this elsewhere, but the instructions are for Heroku)
Getting Started
Create a GitHub Application
Remember the 'my-site' part for later on when using heroku create
. Also, my-site is often called 'app-name' in Heroku documentation.
Add Bunto Auth to your site
-
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 'bunto-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 'bunto-auth'
-
cd
into your project's directory and run bundle install
. If you get an error using bundle install
, see Troubleshooting below.
-
Run bundle exec bunto-auth new
which will copy the necessary files to set up the server
Setting up hosting with Heroku
Automatically
Run bundle exec bunto-auth setup --client_id XXX --client_secret XXX --org_name XXX
(or --team_id XXX
)
Manually
- You may need to add and commit the files generated by
bunto-auth new
to Git before continuing
- Make sure you have the Heroku toolbelt installed
- Run
heroku create my-site
from your site's directory; make sure my-site matches what you specified in the GitHub application registration above.
heroku config:set GITHUB_CLIENT_ID=XXX GITHUB_CLIENT_SECRET=XXX GITHUB_ORG_NAME=XXX
(or GITHUB_TEAM_ID
)
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
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 bunto-auth team_id
command.
For example, to find the team ID for @bunto/maintainers you'd run the command:
bunto-auth team_id --org bunto --team maintainers
You'll want to add a personal access token to your .env
file so that Bunto-Auth can make the necessary API request, but the command will run you through the process if you do not provide this.
Configuration
Whitelisting
Don't want to require authentication for every part of your site? Fine! Add a whitelist to your Bunto's config.yml file:
bunto_auth:
whitelist:
- drafts?
bunto_auth.whitelist
takes an array of regular expressions as strings. The default auth behavior checks (and blocks) against root (/
). Any path defined in the whitelist won't require authentication on your site.
What if you want to go the other way, and unauthenticate the entire site except for certain portions? You can define some regex magic for that:
bunto_auth:
whitelist:
- "^((?!draft).)*$"
Requiring SSL
If you've got SSL set up, simply add the following your your _config.yml
file to ensure SSL is enforced.
bunto_auth:
ssl: true
Using a custom 404
Just like GitHub Pages, Bunto Auth will honor a custom 404 page, if it's generated as /404.html
in the built site.
Running locally
Want to run it locally?
Without authentication
Just run bunto serve
as you would normally.
With authentication
export GITHUB_CLIENT_ID=[your github app client id]
export GITHUB_CLIENT_SECRET=[your github app client secret]
export GITHUB_ORG_NAME=[org name]
or export GITHUB_TEAM_ID=[team id]
or export GITHUB_TEAM_IDS=1234,5678
bunto-auth serve
Pro-tip #1: For sanity's sake, and to avoid problems with your callback URL, you may want to have two apps, one with a local Oauth callback, and one for production if you're going to be testing auth locally.
Pro-tip #2: Bunto Auth supports dotenv out of the box. You can create a .env
file in the root of site and add your configuration variables there. It's ignored by .gitignore
if you use bunto-auth new
, but be sure not to accidentally commit your .env
file. Here's what your .env
file might look like:
GITHUB_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz0123456789
GITHUB_CLIENT_ID=qwertyuiop0001
GITHUB_TEAM_ID=12345
Under the hood
Every time you push to Heroku, we take advantage of the fact that Heroku automatically runs the rake assets:precompile
command (normally used for Rails sites) to build our Bunto site and store it statically, just like GitHub pages would.
Anytime a request comes in for a page, we run it through Sinatra (using the _site
folder as the static file folder, just as public
would be normally), and authenticate it using sinatra_auth_github.
If they're in the org, they get the page. Otherwise, all they ever get is the bouncer.
Upgrading from Bunto Auth < 0.1.0
cd
to your project directory
rm config.ru
rm Procfile
- Remove any Bunto Auth specific requirements from your
Gemfile
- Follow the instructions above to get started
- When prompted, select "n" if Heroku is already set up
Troubleshooting
- ERROR: YOUR SITE COULD NOT BE BUILT during install, either locally or on Heroku. You likely need to add
exclude: [vendor]
to _config.yml
in your branch's root directory (create the file if it does not exist already). If you still have problems on the local install, you may have better luck using bundle install --deployment
, but be sure to add the resulting 'vendor' directory to .gitignore. For completeness, the full error may look something like this:
remote: Configuration file: none
remote: ERROR: YOUR SITE COULD NOT BE BUILT:
remote: ------------------------------------
remote: Invalid date '0000-00-00': Post '/vendor/bundle/ruby/2.0.0/gems/bunto-2.5.3/lib/site_template/_posts/0000-00-00-welcome-to-bunto.markdown.erb' does not have a valid date in the filename.
- Pushing to heroku. If you are working from a new GitHub-cloned repo (where you have not run
heroku create
), you may also want to push to Heroku. Instead of adding the remote in the standard way with Git, do this:
heroku git:remote -a my-site