Deployment 10 min read Beginner Guide

GitHub Pages Custom Domain: Step-by-Step Guide

Set up a custom domain for your GitHub Pages site using a free is-pro.dev subdomain. DNS configuration, repository settings, and SSL setup covered.

Written by Mayank Baswal

Founder of is-cool-me · DNS & Platform Infrastructure

Mayank Baswal maintains the is-cool-me platform and writes technical guides focused on DNS configuration, subdomain infrastructure, SSL troubleshooting, deployment workflows, and platform reliability.

GitHub Profile Contact
Reviewed by is-cool-me Technical Review

GitHub Pages Custom Domain: Step-by-Step Guide

GitHub Pages is one of the most popular ways to host static sites, portfolios, and project documentation. By default, your site lives at username.github.io, but adding a custom domain makes it look professional. With is-pro.dev, you can get a free subdomain and point it to your GitHub Pages site in under ten minutes. This guide covers everything you need to know.

Why Use a Custom Domain with GitHub Pages?

A custom domain like portfolio.is-pro.dev looks much more professional than username.github.io. It builds trust with visitors, improves your brand, and gives you a consistent URL that you can use on resumes, business cards, and social media profiles. Best of all, is-pro.dev subdomains are completely free.

Prerequisites

  • A GitHub account and a GitHub Pages repository (either your username repository or a project page)
  • A registered is-pro.dev subdomain
  • Your GitHub Pages URL (e.g., username.github.io or username.github.io/repository)

Step 1: Register Your Subdomain

Sign in at dash.is-pro.dev with your GitHub account. Choose a subdomain that matches your GitHub Pages site. If you are creating a portfolio, portfolio.is-pro.dev is a great choice. For a project documentation site, use the project name. Complete the registration and your subdomain will be ready in seconds.

Step 2: Configure DNS Records

GitHub Pages requires specific DNS records depending on whether you are using an apex domain or a subdomain. For an is-pro.dev subdomain, you need to add DNS records in your dashboard:

For a subdomain (recommended): Create a CNAME record pointing your subdomain to username.github.io. Replace username with your actual GitHub username.

For an apex domain (if you have one): Create A records pointing to GitHub's IP addresses: 185.199.108.153, 185.199.109.153, 185.199.110.153, and 185.199.111.153.

Step 3: Configure Your GitHub Repository

Go to your GitHub repository and navigate to Settings → Pages. Under "Custom domain," enter your full subdomain (e.g., portfolio.is-pro.dev) and click Save. GitHub will automatically create a commit adding a CNAME file to your repository. This file tells GitHub Pages which domain to serve your site on.

Step 4: Enable HTTPS

After you save your custom domain, GitHub will attempt to provision a Let's Encrypt SSL certificate. This process is automatic and usually takes a few minutes. Check the "Enforce HTTPS" checkbox once the certificate is ready. This ensures all traffic to your site is encrypted.

Step 5: Verify Your Setup

Visit your new domain in a browser. Your GitHub Pages site should load with a valid HTTPS certificate. Check that all links, images, and resources load correctly. If your site uses relative URLs, they will work automatically with your new domain.

Troubleshooting

404 error after setup: If you see a 404, check that your CNAME record is exactly correct. The target should be username.github.io with no trailing slash. Also verify that GitHub Pages is enabled for your repository.

SSL certificate not ready: GitHub provisions certificates automatically, but this can take up to 24 hours in rare cases. If it takes longer than an hour, try removing and re-adding your custom domain in the Pages settings.

Mixed content warnings: If your site loads over HTTPS but some resources load over HTTP, update all resource URLs to use HTTPS or protocol-relative URLs (starting with //).

FAQ

Q: Can I use multiple custom domains with one GitHub Pages site?

A: GitHub Pages supports one custom domain per site. However, you can set up redirects from other domains.

Q: Will GitHub Pages still work with my existing GitHub Actions deployment?

A: Yes, custom domains do not affect your deployment workflow. GitHub Actions will continue to deploy as usual.

Q: Can I use a subdomain for a project page?

A: Yes. For project pages, create a CNAME pointing to username.github.io and add the CNAME file with your custom domain to your project repository.

Conclusion

Setting up a custom domain for GitHub Pages with a free is-pro.dev subdomain is straightforward. Register your subdomain, configure DNS, update your repository settings, and enable HTTPS. Your site will be live with a professional, custom URL in just a few minutes.