Set Up GitHub Pages with a Custom Subdomain

What You Will Learn

• How to configure DNS for GitHub Pages
• Setting up a custom subdomain with your GitHub Pages site
• Enforcing HTTPS on your Pages custom domain
• Avoiding common pitfalls with apex domains and CNAME records

Requirements

• A verified is-pro.dev subdomain
• A GitHub repository with GitHub Pages enabled
• Access to your repository settings
• Basic understanding of DNS

Background Information

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files directly from a repository on GitHub. It is a free and popular choice for project documentation, personal portfolios, and project landing pages. By default, every Pages site is served on a github.io subdomain — for example, yourname.github.io or yourname.github.io/repository.

Using a custom subdomain like project.yourname.is-pro.dev makes your site look more professional and reinforces your brand. GitHub Pages supports custom domains through DNS configuration: you point a CNAME record at GitHub's servers, and GitHub handles the rest, including automatic TLS certificate provisioning through Let's Encrypt.

This guide walks through the complete process of connecting an is-pro.dev subdomain to a GitHub Pages site, from adding the CNAME record to enforcing HTTPS. DNS changes, TLS certificate issuance, and GitHub's domain verification each have their own timing considerations; we will cover all of them so you can debug issues on your own.

Step-by-Step Setup

Step 1: Enable GitHub Pages in Your Repository

Before you can attach a custom domain, the repository itself must be configured to publish via Pages.

1. Navigate to your repository on GitHub.
2. Click Settings > Pages in the left sidebar.
3. Under Branch, select the branch you want to deploy (commonly main or gh-pages) and optionally set the /root or /docs folder.
4. Click Save. GitHub will display a public URL — usually something like https://yourname.github.io/repository/.

At this point your site is live on the default github.io domain. Verify it works before introducing the custom domain — this isolates DNS issues from build issues.

Step 2: Add Your Custom Domain in GitHub Pages

Once Pages is active, tell GitHub which custom domain you intend to use.

1. In the same Pages settings panel, locate the Custom domain field.
2. Enter your full subdomain, for example project.yourname.is-pro.dev.
3. Click Save.

GitHub immediately performs a DNS check. It will try to resolve a CNAME record at project.yourname.is-pro.dev pointing to yourname.github.io. If the DNS record does not yet exist (we add it in the next step), GitHub will show a warning — this is expected. Proceed anyway.

Step 3: Configure DNS in is-cool-me Dashboard

Now you need to create the DNS record that points your subdomain at GitHub's servers.

1. Log in to https://dash.is-pro.dev.
2. Select the subdomain you want to use and click Add Record.
3. Fill in the fields:
   • Type: CNAME
   • Name: your subdomain prefix (e.g., project)
   • Target: yourname.github.io
   • TTL: 300 seconds (5 minutes)
4. Click Create Record.

Step 4: Enforce HTTPS

With the DNS record in place, GitHub can complete its domain verification and provision a TLS certificate.

1. Return to your repository's Pages settings on GitHub.
2. Check the box labeled Enforce HTTPS.
3. Wait. The certificate provisioning typically takes 5–15 minutes but can occasionally take up to an hour if DNS is still propagating across all global resolvers.

Step 5: Verify the Setup

1. Open your custom subdomain in a browser: https://project.yourname.is-pro.dev.
2. Confirm the page content matches your GitHub Pages site.
3. Click the padlock icon in the address bar and verify that the SSL certificate is valid and issued to your subdomain.
4. Try visiting the http:// version — it should redirect to https://.

Verification

Use command-line tools to confirm each layer works independently:

# Check that the CNAME record resolves
dig project.yourname.is-pro.dev CNAME +short
# Expected output: yourname.github.io.

# Verify the A record resolves to GitHub's IPs
dig yourname.github.io A +short
# Expected: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153

# Check HTTPS with curl
curl -sI https://project.yourname.is-pro.dev | head -n 1
# Expected: HTTP/2 200

If any of these checks return unexpected results, proceed to the troubleshooting section below.

Troubleshooting

Here are the most common issues and how to resolve them:

1. CNAME record already exists

Cause: GitHub's automatic CNAME file commit conflicts with an existing file in your repository, or you have previously configured the same domain.

Fix: Pull the latest commit that GitHub created, resolve any merge conflicts, and push. If the CNAME file already exists with the correct domain, no action is needed.

2. SSL certificate pending

Cause: The DNS record has not propagated to all authoritative resolvers, so Let's Encrypt cannot verify domain ownership.

Fix: Wait. Use dig from different networks to confirm the CNAME is visible worldwide. If it has been more than an hour, double-check the record type, name, and target in the is-cool-me dashboard.

3. Domain not found in Pages

Cause: A typo in the subdomain, or the CNAME file in the repository contains a different value than what you entered in the Pages settings.

Fix: Verify the exact domain string in both places. The CNAME file at the root of your publishing branch must match the custom domain field in Settings > Pages character-for-character.

4. DNS propagation delays

Cause: Your local resolver or upstream DNS servers are caching a stale response based on the previous TTL.

Fix: You can bypass your local cache by querying a public resolver directly: dig @8.8.8.8 project.yourname.is-pro.dev CNAME. Lower the TTL to 60 or 120 seconds while testing.

5. Mixed content warnings

Cause: Your page includes HTTP resources (images, scripts, stylesheets) while the page itself is served over HTTPS. Browsers block or warn about these requests.

Fix: Use protocol-relative URLs (//cdn.example.com/file.js) or ensure all external resources use https://. Check your browser's developer console for blocked requests.

6. Redirect loop or wrong site

Cause: A leftover CNAME record pointing to a different GitHub Pages site, or another service (like a CDN or reverse proxy) intercepting the traffic.

Fix: Remove any stale DNS records in the is-cool-me dashboard. Check that no other CNAME, A, or AAAA records exist for the same subdomain name.

Best Practices

• Keep your CNAME file in the repository root. This ensures the custom domain survives branch switches, clones, and CI deployments.
• Do not use A records for the custom domain. GitHub Pages used to recommend pointing apex domains at their IP addresses via A records, but CNAME records are the modern approach and are required for HTTPS certificate provisioning.
• Use a separate subdomain for each project. Each GitHub Pages site in a given account can have at most one custom domain. Using distinct subdomains avoids conflicts and makes DNS management straightforward.
• Monitor GitHub Pages build status. If your site stops serving, check the Pages settings for a build error or a red banner. Sometimes a failed build resets the custom domain configuration.
• Set a reasonable TTL. Start with 300 seconds during initial setup. After everything is verified, increase to 3600 seconds or higher to reduce DNS query load.
• Use a .is-pro.dev subdomain rather than a sub-subdomain. For example, prefer myrepo.username.is-pro.dev over sub.username.is-pro.dev. The latter requires additional CNAME configuration that can introduce unnecessary complexity.

FAQ

Does GitHub Pages support apex domains?

GitHub Pages technically supports apex (bare) domains via A records pointing to their IP addresses. However, apex domains cannot get Let's Encrypt certificates through GitHub's automated process because the CNAME-based verification requires a CNAME at the domain root, which is not allowed by the DNS specification. On is-pro.dev, always use subdomains for automatic HTTPS.

How long does SSL take to provision?

Typically 5–15 minutes after the DNS record resolves correctly. In rare cases with slow DNS propagation it can take up to an hour. If the Enforce HTTPS checkbox is still greyed out after an hour, double-check your DNS record and try removing and re-adding the custom domain in GitHub Pages settings.

What if I get a 404 error?

A 404 means GitHub Pages is active but cannot find your content. Check that your repository has an index.html in the root of the publishing branch. Also verify the Source setting in Pages — if it points to the /docs folder, your index file must live there.

Can I use a custom domain with a private repository?

Yes, but GitHub Pages on private repositories requires a GitHub Pro, Team, or Enterprise plan. Free accounts can only use Pages on public repositories. The custom domain setup process is identical regardless of visibility.

What happens if I remove the CNAME file?

On the next deployment (or after a few minutes), GitHub Pages resets your custom domain to the default github.io URL. The custom domain field in Settings > Pages will also clear. Your DNS record will still point at GitHub, so visitors will get a 404 until you either restore the CNAME file or the DNS record propagates away.

Can I use multiple custom domains for one Pages site?

No. GitHub Pages supports a single custom domain per repository. If you need multiple domains pointing to the same site, you will need to set up an external redirect service or use a reverse proxy — neither of which is covered in this guide.

Does GitHub Pages support HTTPS for custom domains?

Yes. GitHub Pages provisions TLS certificates automatically through Let's Encrypt for custom domains that have a correctly configured CNAME record. This is a free, first-class feature — no manual certificate management required.

How do I fix a "domain does not resolve to GitHub" error?

This error appears in GitHub Pages settings when the DNS check fails. Run dig yoursubdomain.yourname.is-pro.dev CNAME and confirm the output is exactly yourname.github.io. (with a trailing dot). If the record is missing or incorrect, update it in the is-cool-me dashboard and wait for propagation. If the record looks correct, GitHub may still be catching up — wait a few minutes and reload the Pages settings page.

Related Guides

• Connect Vercel with is-pro.dev
• Connect Netlify with is-pro.dev
• Diagnose SSL Pending on a New Subdomain

Conclusion

Connecting a custom subdomain to your GitHub Pages site involves three main pieces working together: your repository's Pages configuration, a CNAME DNS record in is-pro.dev, and GitHub's automatic TLS certificate provisioning. Each layer has its own timing and verification steps.

When something goes wrong, isolate the problem: use dig to verify DNS, check the Pages settings for error banners, and inspect your browser's SSL certificate details. Most issues are caused by DNS propagation delays or a mismatch between the CNAME file in the repository and the custom domain field in Settings.

Once everything is working, your custom subdomain will serve your GitHub Pages site over HTTPS with a valid Let's Encrypt certificate — all managed automatically. If you run into trouble, the is-pro.dev Discord community is a great place to ask for help.

Deployment scenario from operations

A project repo changed its Pages branch and forgot to align DNS records with the new published endpoint.

Common mistakes

• Using stale GitHub Pages target records after repository changes.
• Forgetting to update the repository CNAME file.
• Assuming DNS is broken when build publishing actually failed.

How to verify it works

1. Check DNS answers against expected GitHub Pages records.
2. Confirm repository CNAME file matches final host.
3. Verify the published page serves over HTTPS without mixed-content errors.