Skip to content

Instantly share code, notes, and snippets.

Created July 16, 2011 11:23
What would you like to do?
How to: GitHub Pages "gh-pages" branch for User & Organization Pages

GitHub Pages "Normal" Setup for User & Organization Pages

Let’s say your GitHub username is “alice”. If you create a GitHub repository named, commit a file named index.html into the master branch, and push it to GitHub, then this file will be automatically published to The same works for organizations.

Read more here:

However... the downside of this is that anyone that forks this repo won't get it as a GitHub Pages repo when they are working on it... because they have a different GitHub "username" (or "organisation name").

So the trick is to not use a master branch as the documentation tells you... rather, use a gh-pages branch, as you would for your other "Project Pages".


  1. Create a New Repository on GitHub (don't follow any of the suggested setup instructions).
  2. mkdir
  3. cd
  4. git init
  5. git branch -m master gh-pages <- renames the "master" branch to "gh-pages"
  6. echo "<h1>Hello Alice</h1>" > index.html
  7. git add index.html
  8. `git commit -m "initial commit"
  9. `git remote add origin
  10. git push -u origin gh-pages


This process is most likely most useful for Organization Pages...

I'm personally using it for my "viewsource" organization... which is an open source GitHub Pages hosted CDN.

Copy link

mhulse commented Jul 16, 2012

For some reason I get:

error: refname refs/heads/master not found
fatal: Branch rename failed

When I try to rename my master branch to gh-pages.

Copy link

Try adding something and committing so that the ref will be available, first.

Copy link

Hello, I'm new to GitHub and when I try to push it says

Warning: Permanently added ',' (RSA) to the list of know
n hosts.
ERROR: Repository not found.
fatal: The remote end hung up unexpectedly

what can I do to avoid this? Thanks :)

Copy link

towolf commented Mar 12, 2013

Doesn't work.

Copy link

If anyone has issues with this it is because you don't have an upstream branch yet.
To fix use:
git push --set-upstream origin gh-pages

Copy link

I am having your current problem: page not found for

Copy link

amabes commented Apr 27, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment