## Getting Started

### Create a GitHub Application

1. Navigate to [the GitHub app registration page](https://github.com/settings/applications/new)
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](https://help.github.com/articles/creating-project-pages-manually/) (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:

   ```ruby
   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](https://toolbelt.heroku.com/) 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](https://github.com/settings/tokens/new) 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.