5 Steps to host a static web page on GitHub

GitHub, constantly updated, has recently made hosting easy and allows you to set up a custom domain. From an engineering point of view, it may be easier than renting a server. Simple static pages can be created quickly and easily. It also supports custom domains and HTTPS!

This article explains how to host a static page using GitHub. Please note that we will start with the assumption that you have already purchased a domain name and have the coding data for your website in the GitHub repository.

What we used this time
- GitHub Actions, GitHub Pages
- Vite
- Google Domains

In fact, we hosted our own website with this.
https://bug-fix.org/

Please note that hosting on GitHub Pages requires either an upgrade to the Enterprise Plan (paid) or that the repository is Public. Please choose one or the other, depending on your situation.

1. Set up your domain on GitHub 1/2

Set up a purchased domain on GitHub. Go to the account setup page (https://github.com/settings/pages) and click the “Add a domain” button.

Enter the domain you purchased in the “What domain would you like to add?”

You will then be redirected to the “Add a verified domain” page. Copy and write down the TXT record information in 1 and 2, leave this page open, and move on to the domain service side of the setup.

*If you are considering transferring a domain name from some hosting service rather than acquiring a new one, you will need to deactivate the domain name from that hosting service first.

2. Set up DNS for the purchased domain

This is the process of setting up the DNS for the domain you have purchased and connecting it to GitHub. After this, GitHub will authenticate the domain, and by doing so, GitHub will recognize that you are the owner of the domain.

In this case, we purchased the domain from Google Domains, so we will show you how to do this on their management screen. Although the UI may be different, the DNS setup procedure is generally the same for all services.

First, go to the domain management page (https://domains.google.com/registrar/) and select any domain.

Since I am a Japanese user, this article often uses captured images in Japanese sorry. I will provide the English translation in blue instead.

Select “DNS” from the left side menu and click the “Manage Custom Records” button. Select “DNS” from the left side menu and click the “Manage Custom Record” button.

This will take you to a page labeled “Resource Records.” Regarding the input screen in 1, you can enable access from GitHub’s IP address here.

The IP addresses of GitHub in the A record are the following four at the time of writing (Apr 26, 2024).

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

The latest information is available on the official page, so we recommend you check the information here.

Managing a custom domain for your GitHub Pages site - GitHub Docs

Let’s go back to the record setup screen again and explain the part about input field 1…
The hostname can be left blank because any domain will be set by default.
Type refers to the type of record. In this case, “A” is set. TTL is set to 3600, meaning one hour.
And set the data to the IP address of GitHub, as mentioned earlier. Click the “Add more records” link to increase the number of input fields and set four.

Next, let’s look at input field 2. Here, enter the TXT record information that you wrote down on the GitHub setup screen. The hostname will be followed by “.domain-name” added at the end of the hostname, like “xxx.domain-name”.

Click the “Save” button in the lower right corner to complete the DNS configuration for the domain.

And you can verify the result by inputting the command dig {your domain name} + noall + answerin CLI. It succeeds if the following values return.

3. Set up your domain on GitHub 2/2

Next, go back to GitHub and complete the domain verification. On the screen that is still open, click the “Verify” button at 3.

If the configuration is successful, it will be added to the “Verified domains” section with the label “Verified”.

You will get a message saying that it will take up to 24 hours, but in my case, it took only a couple of minutes. That’s very fast.

4. Build and Hosting Settings in the Repository

Now comes the final stage! Click on the tab menu “Settings” in the upper right corner of the GitHub repository page where the website data is stored, then click on “Pages” in the left side menu.

Under “Source,” select the build method. Deploy from a branch” is simple and may be fine, especially if you are creating static pages that do not need to be built. In that case, set “Branch” below to any branch. When data is pushed to the branch set here, it will be hosted immediately with the directory structure as it is.

If you are using Webpack, Vite, Next.js, etc., you will need to build them, so select “GitHub Actions”. Two menus will appear. Since this is a static site, click the “Configure” button under “Static HTML.

This will take you to the `/.github/workflows/static.yml` edit screen. The settings described here will be executed at build time using GitHub Actions.

The contents will vary depending on the framework you are using. In the case of Vite, there is a specific description on the official page, so you can almost copy and paste.

https://vitejs.dev/guide/static-deploy.html#github-pages

This is all of the code.

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Let me emphasize the important parts in two places just in case.

• `on.push.branches` … The name of the branch you are hosting. The default is main, but if you change the branch name, change this as well.
• `jobs.deploy.steps.with.path` … The path to the output directory of the data to be built when npm run build is executed. Default is `. /dist` by default, but if you have changed it, change it here as well.

When you have finished making changes, click “Commit changes…” in the upper right corner of the screen. in the upper right corner of the screen.
This will create the file “/.github/workflows/static.yml” on the GitHub page, and commit and push the file, so pull it locally as well.

You will return to the GitHub repository page. Enter the domain name in the “Custom domain” entry field and click the “Save” button. If the process up to this point has been successful, you can Save without any problems, but please note that an error will occur if you make a mistake somewhere.

5. Hosting with GitHub Actions

After all this is done, let’s push the data to the branch you have set up (main by default). If successful, a “Visit site” button will appear on the Pages screen of the repository, which you can access from here.

If you want to know whether the deployment was successful or not, and if so, what was the cause, you can view the history in the “Actions” tab of the repository. You can also click on the history of failures to see the error details and logs, which can be used as hints to fix the problem.

If it does not work…

Even if you proceed as described here, it may not work as expected.

• When setting a custom record, the message “IPv4 address is invalid” is displayed
• The above command does not return as expected.
  In such cases, please try the following.

First, set the DNS record type to “ALIAS or ANAME” instead of “A” when setting the custom record.
Then set “TTL” to 3600 and “DNS record value” to “USERNAME.github.io”.
For example, in my case, my GitHub user name is “seito-developer”, so the DNS record value is “seito-developer.github.io”.
Below is an example of the input on the administration screen when setting up with a Google domain.

This is what GitHub’s official.

Managing a custom domain for your GitHub Pages site - GitHub Docs

Then again, enter the desired domain in “Custom domain” in “GitHub Pages” and authenticate again. This will take a few minutes, but if all goes well, you will see a “DNS check successful” message.

Then make some changes again and update the repository by pushing to the main branch. This will trigger a GitHub Action and deploy automatically.
You can make any changes you want (e.g., change one character in the README).

Now, when you access your domain, it should reflect the changes. (It may take a few minutes)

Do you wanna set up the subdomain “www,” too?

In addition, we will also specify here how to set up a www subdomain.
This will make it possible to automatically redirect accesses to “https://www.bug-fix.org/" to “https://bug-fix.org/" and so on.

The setting method is simple. Set the subdomain “www” in the same way as setting a DNS record. Access the administration screen of the domain management service and set the custom record settings as follows.

• Host name: www
• DNS record type: CNAME
• TTL: 3600
• DNS record value: USERNAME.github.io (*)

For example, in my case, my GitHub user name is “seito-developer”, so the DNS record value is “seito-developer.github.io”. Below is an example of the input on the administration screen when setting up with a Google domain.

After this, you need to access “GitHub Pages” again, authenticate with “Custom domain” & update the repository, push, and run the GitHub Action. This process should be automatic, but it is a good idea to check it visually as well.

Create CNAME” is automatically created and pushed.

That’s it, thanks!