How to Upload Your Startup Website to GitHub Pages

GitHub is a platform that offers software developers a place to host their code and manage their software products. Other than offering a place where you can save your code, GitHub offers another service called GitHub Pages that allows you to host a website on their platform for free.

We highly recommend trying out the Static.app, a superior hosting service for static websites. It’s extremely user-friendly, allowing you to upload your HTML template and see it live in less than a minute. The best part is that no additional setup is required on your part.

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process and publishes a website. You can use it to host a website about yourself, your organization, or your project.

However, there are some caveats that you should be aware of before deciding to host your Startup website on GitHub Pages:

• GitHub Pages, being a static site hosting service, does not support server-side languages such as PHP, Ruby, or Python. The Startup app offers an option for collecting data via forms and sending the data to an email address. We do the form processing via a PHP script found in the form-handler.php file. If you are going to have forms on your website and want to process the data with the PHP file, then your website has to be hosted on a platform that supports PHP and the PHP mail() function. You can, however, still host your website on GitHub Pages and have forms to collect data, but you have to rely on third-party form providers like Formspree, Kwes, FormKeep, e.t.c. Here is a comparison of some available options and here is a tutorial that will show you how you can edit your Startup forms to use one of these services (Formspree, in this case). If you decide to stick with the PHP script, then check the help docs to find out how to receive data from forms and how to set up Mailchimp using the form-handler.php script file.
• GitHub Pages enforces some quotas on the websites it hosts and thus it’s not suitable to host large websites that might have a lot of traffic. It is suitable for modest websites, like personal portfolios, simple organization websites, project landing pages. It is not suitable for e-commerce websites or for large websites for running your online business. The given quotas are: published GitHub Pages sites may be no larger than 1 GB and GitHub Pages sites have a soft bandwidth limit of 100GB per month.

Creating a GitHub Pages Site

There are three types of GitHub Pages sites: user, organization and project. User and organization sites are connected to a specific GitHub account, while project sites are connected to a specific project hosted on GitHub.

We are going to create a User site, but the process is similar for organization and project sites. Where there are differences, we’ll mention them.

Before you can get started, first create an account on GitHub.

On GitHub, projects are stored in repositories. A repository is like a folder for your project, that contains all of the project’s files, and stores each file’s revision history. You’ll need to create a repository for your site.

To create a repository on GitHub, click on the + icon at the top-right of the navigation bar and select New repository.

Fill out the Create a new repository form with details about the repository. At the very least, you have to include the name of your repo.

For a user site, the name of the repository has to be <username>.github.io. For an organization, the repo has to be named <organization-name>.github.io. For instructions on how to create an organization, check this help document. If you are creating a project site, you don’t need to create a separate repository for the site’s files, you store the site’s files in the same repository as the associated project.

GitHub Pages is available in public repositories with GitHub Free, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. If you have a premium account and decide to make the repository private, keep in mind that GitHub Pages sites are publicly available on the internet, even if their repositories are private. Therefore, in case you have sensitive data in your site’s repository, you may want to remove it before publishing.

After the repository is created, you’ll see a page with instructions on how to upload files to it.

If you are familiar with the Git version control system, then you can upload your website files to the repository in this way. To keep it simple, we’ll use GitHub’s UI to upload the files. GitHub has a detailed help document on how to set up and use Git if you are interested.

To upload your website’s files to the repository, click on the uploading an existing file link shown below, or add /upload to the page’s URL and head over to that page (i.e ).

On the upload page, you can drag-and-drop files and folders and they will be added to the repo. Go to the root directory of your Startup website code, select everything, then drag it to the page.

It is better to use drag-and-drop than to use the choose your files link to select files from your computer. With drag-and-drop, you’ll be able to drag both files and folders to the page and when the files are uploaded, they’ll be in their respective folders. With the choose your files option, you will only be able to select files and not folders. With this option, you will upload all the Startup files to the root directory of the repository and then have the added task of editing the file names to include the directory structure.

As mentioned previously, the PHP code in the form-handler.php script file won’t run on GitHub Pages, but we include it with the rest of the website’s files to keep everything belonging to that site together. This is a good idea because, in the future, you might want to transfer the website to a PHP server and the files on GitHub might be the only copy of the website you have available, so you’ll be glad you kept a copy of the PHP file.

At the bottom of the page, you can add a commit message (otherwise the default Add files via upload will be used) before committing the changes. The good thing about GitHub is that different versions of your files are saved. Every time you make changes to the files, a version is created of the new files. This means that you can restore a previous version of your files, so, for instance, if you upload a version 5 of your website, but decide against it, you can easily go back to a previous version of the website. So you should include a commit message to your commits that will make it easy for you to identify different changes you’ve made, in case you ever want to undo a specific change in code.

Commit the changes and you will be able to see the files and folders you just committed.

Believe it or not, your website is already online!

After a GitHub Pages site is published, you can access it by going to http(s)://<username>.github.io for a user site, or http(s)://<organization-name>.github.io for an org site or http(s)://<username>.github.io/<repository-name> for a project created under the user or http(s)://<organization-name>.github.io/<repository-name> for a project created under an organization. You can also use a custom domain for your site. We’ll see how to set this up later on.

Something to Note About Project Sites

Git has a feature called branching that allows you to create a branch of your code and keep working on this new branch without affecting the old branch. Every GitHub repository has a master branch and from this, you can create other branches.

This is relevant as there are rules you must follow when it comes to the branch you can place your website code in for it to be published. User and Organization sites have to be on the master site. By default, when you create a repository, it is on the master branch, so we didn’t need to set up additional branches.

By default, project sites are set up to be published from a branch named gh-pages. If you are creating a project site, check here for instructions on how to create a branch on GitHub.

Project sites can also be published from the master branch or a /docs folder on the master branch. To publish your site from one of these sources, you must configure a different publishing source for the site.

Making Changes to Your GitHub Pages Site

The GitHub UI has controls that you can use to add, delete and edit your website’s files.

You can use the Add file dropdown to upload a file or create a file using the GitHub UI. Make sure you are in the right folder when you add a file.

To delete a folder, you only have to delete the files it holds. GitHub doesn’t list empty directories, so emptying a folder essentially deletes it.

When you select a file, you’ll be able to edit or delete it using the last two controls shown below.

Once you’ve made changes to your site’s files, you’ll be able to see the changes on the website almost immediately.

Configuring a Custom Domain for Your GitHub Pages Site

You can customize the domain name of your GitHub Pages site from the default, like <username>.github.io, to a domain that you own. It supports subdomains (e.g. a www subdomain like www.example.com or a custom subdomain like blog.example.com) and apex domains (e.g. example.com). You can set up either or both types of custom domains for your site. It is recommended that you always use a www subdomain, even if you’ll also use an apex domain.

Configuring a Subdomain

To set up a www subdomain (such as www.example.com) or a custom subdomain (such as blog.example.com), you must create a CNAME file in your site’s repository and configure a CNAME record with your DNS provider.

Navigate to your repository’s Settings tab.

Scroll down to GitHub Pages. Under Custom domain, type your custom domain, then click Save. This will create a commit that adds a CNAME file in the root of your publishing source.

Navigate to your DNS provider and create a CNAME record that points your subdomain to the default domain for your site (e.g. create a CNAME record that points www.example.com to <username>.github.io). For instructions on how to create the CNAME record, look at your DNS provider’s documentation.

To confirm that your DNS record configured correctly, you can use the dig command in the Terminal (Command Prompt, for Windows), replacing www.example.com with your subdomain.

$ dig www.example.com +nostats +nocomments +nocmd

If configured correctly, you should get output that is similar to the one shown below.

;www.example.com.        IN    A
www.example.com.    3592    IN    CNAME    example.github.io.
example.github.io.    3592    IN    A    185.199.111.153
example.github.io.    3592    IN    A    185.199.110.153
example.github.io.    3592    IN    A    185.199.109.153
example.github.io.    3592    IN    A    185.199.108.153

Configuring an Apex Domain

To set up an apex domain (e.g. example.com), you must configure a CNAME file in your GitHub Pages repository and an ALIAS, ANAME, or A record with your DNS provider.

Navigate to your repository’s Settings tab.

Scroll down to GitHub Pages. Under Custom domain, type your custom domain, then click Save. This will create a commit that adds a CNAME file in the root of your publishing source.

Navigate to your DNS provider and create either an ALIAS, ANAME, or A record. For instructions on how to create the correct record, take a look at your DNS provider’s documentation.

To create an ALIAS or ANAME record, point your apex domain to the default domain of your site (<username>.github.io).

To create an A record, point your apex domain to the IP addresses for GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

To confirm that your DNS record configured correctly, use the dig command in the Terminal (Command Prompt, for Windows), replacing example.com with your apex domain.

$ dig example.com +noall +answer

Confirm that the results match the IP addresses for GitHub Pages shown previously.

example.com.        3600    IN    CNAME    example.github.io.
example.github.io.    3600    IN    A    185.199.111.153
example.github.io.    3600    IN    A    185.199.108.153
example.github.io.    3600    IN    A    185.199.109.153
example.github.io.    3600    IN    A    185.199.110.153

As previously mentioned, if you are using an apex domain as your custom domain, it is recommended that you also set up a www subdomain. With the correct records configured for each domain type through your DNS provider, GitHub Pages will automatically create redirects between the domains. For example, if you configure www.example.com as your custom domain for your site, and you have ALIAS and CNAME records set up for the apex and www domains, then example.com will redirect to www.example.com.

Securing Your GitHub Pages Site With HTTPS

HTTPS enforcement is required and enabled by default for GitHub Pages sites using a github.io domain that was created after June 15, 2016. For sites created before June 15, 2016, you can manually enable HTTPS enforcement by going to your repo’s Settings, scrolling down to GitHub Pages and checking the Enforce HTTPS checkbox.

Domain Errors to Be Aware Of

Make sure your site doesn’t:

• Use more than one apex domain. For example, both example.com and anotherexample.com.
• Use more than one www subdomain. For example, both www.example.com and www.anotherexample.com.
• Use both an apex domain and a custom subdomain. For example, both example.com and docs.example.com.

Unpublishing a GitHub Pages Site

You can unpublish your GitHub Pages site so that it is no longer available to the public. Deleting a repository will cause the site to be unpublished.

If you want to keep the repository, but still have the website unpublished, you should delete its publishing source—the master branch for user and organization sites and the gh-pages branch for project sites (or whichever branch you set as the publishing source). Since the master branch is the default branch, you’ll first have to set another branch as the default, before you can delete the master branch.

For project sites, if you had used the gh-pages branch as your publishing source, all you have to do is delete the branch and the website will be unpublished. If you had used another branch as the publishing source, then there is an extra step to perform.

Navigate to the repository’s Settings tab:

Scroll down to the GitHub Pages section and select None from the Source drop-down menu.

As a final step, if you had set up a custom domain for your user, organization or project site, make sure that you update your DNS settings so that the domain doesn’t keep pointing to the non-existent website.

That’s it for the GitHub Pages set up. If you need further help you can reach out to us or you can take a look at the GitHub pages documentation. If you are interested in using your Startup template on WordPress, we have a tutorial for that as well.