Where Are My GitHub Pages?

Posted on October 2, 2023  •  3 minutes  • 556 words

This site runs on GitHub Pages, and while it’s a great feature, it was initially a bit confusing to understand where everything should be.

There are three main types of GitHub Pages:

• GitHub Pages for a GitHub user
• GitHub Pages for a GitHub organization
• GitHub Pages for a specific repo

GitHub Pages for a GitHub User or Organization

Consider this the primary “site” for an account. GitHub Pages for an account (or organization) is a general site not tied to a specific repository. However, it resides in a repository with a special name: [username].github.io or [organization].github.io. If this repository doesn’t exist, create it.

Once you have this repository, you can enable and configure Pages under the repo’s Settings -> Pages. You can find more details on this process here .

Notes on this:

• You can have only one of these per account or per organization.
• This is what you want if you want to associate a top-level domain with the site and all your other repositories that use GitHub Pages.
• Once set up, any commits to this repo will trigger a redeployment.

GitHub Pages for a Specific Repo

This is a set of GitHub Pages specific to a single repository. Any repository can be configured to have its own GitHub Pages, and the content will be accessible at https://[domain]/[repo-name]. Setting this up is essentially the same as setting up GitHub Pages for a “user” or “organization” site.

Notes on this:

• You can have as many of these as you have repositories.
• If you have a “user” or “organization” site set up with a custom domain, this site will appear under the same domain name (e.g., https://www.bar.com/[repo-name]).
• If you have a “user” or “organization” site set up without a custom domain, this site will appear under https://[username].github.io/[repo-name] or https://[organization].github.io/[repo-name].
• If you set up a unique custom domain for this site, the site will be available directly under that name (at the “root,” e.g., http://foo.bar.com/ without the /[repo-name] after the hostname).

Notes on Custom Domain Names

Setting up content to appear when a user navigates to https://foo.bar.com

Option 1 - Using a “regular” repository

• Create a repository with any available name.
• Create a CNAME DNS record pointing foo.bar.com -> [user/organization].github.io.
• Enable GitHub Pages in this repository (Settings -> Pages).
• Set the custom domain in the settings.

There will be some DNS validation that occurs automatically before the site goes live.

Option 2 - Using a user or organization repository

Option 2 is almost identical to Option 1, but it involves creating a repository with the name [username].github.io or [organization].github.io.

• Create a user or organization repository named [user/organization].github.io.
• Create a CNAME DNS record pointing foo.bar.com -> [user/organization].github.io.
• Enable GitHub Pages in this repository (Settings -> Pages).
• Set the custom domain in the settings.

There will be some DNS validation that occurs automatically before the site goes live.

What is the difference?

In both cases, you’re pointing a CNAME to [user/organization].github.io and then associating your custom DNS name in the repository settings. The difference is that when you use the specially named [user/organization].github.io repository, it also serves as a potential parent to any of your other GitHub Pages that may be present in your other repositories.

So which should I use?

In summary, use Option 1 if you want a standalone site with a custom DNS name and nothing more.