Open navClose nav

GitHub Pages

Disclaimer

This guide assumes you already have an existing Forestry Account, GitHub account, and a repository with a Jekyll or Hugo project. If you don’t have an existing project, check out our Quick start guide, which contains guides and resources for building your first static site.

Getting Started

To deploy a static site to GitHub pages using Forestry, you must first set up a new branch named gh-pages on your repo, which you can do by going to your repository in GitHub and using the branch management dropdown.

https://res.cloudinary.com/forestry-demo/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2018/01/github-gh-pages-settings.png

Configuring Forestry

Once your new branch is created, navigate to the Settings page of your site in Forestry, click the Hosting tab, and set the Connection option to GitHub Pages.

https://res.cloudinary.com/forestry-demo/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2018/01/29.pngIf you haven’t authenticated with GitHub before, you’ll be prompted to choose “Public Repos” or “Private Repos”. Choose the option the applies to your repository.

https://res.cloudinary.com/forestry-demo/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2018/01/1.png

This will redirect you to GitHub, and prompt you to enter your login credentials if you are not already logged in.

https://res.cloudinary.com/forestry-demo/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2018/01/45.png

Give Forestry access to your GitHub repositories by clicking “Authorize application”. You can also request access to any GitHub organizations you are a member of.

In order to host a site with GitHub Pages, you will need admin permissions for the repository. This is because Forestry needs to add a web hook to your repository in order to watch for changes.

Once authorized, you will be redirected back to Forestry.

https://res.cloudinary.com/forestry-demo/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2018/01/43.png

Next, choose your repository, select the new gh-pages branch, and then click Save Settings.

From here on, every time you save or publish a page Forestry will build your site and deploy to this branch.

Enable GitHub Pages

To have GitHub pages begin serving from your new branch, go to the Settings page of your GitHub repository and scroll down to the GitHub Pages section.

Then select the branch that contains your built static site and click on the Save button.

https://res.cloudinary.com/forestry-demo/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2018/01/41.png

Your site should now be served at http://username.github.io/repository.

Using a Custom Domain

If you want to use a custom domain with GitHub Pages, you will need to include a CNAME file containing your custom domain. If you manually add this file to your gh-pages branch, it will be deleted the next time Forestry deploys your site. The CNAME file should instead be added to your source files, in a location where it will be copied to the generated site. In the case of a Hugo site, this should be in your static/ directory, while it can live in the root of your project if you’re using Jekyll.

GitHub Help: Using a Custom Domain With GitHub Pages

Forestry: Troubleshooting CNAME files


Last updated on August 17, 2018