Connect an is-a.dev Subdomain to a Personal GitHub Pages Site

Thu, 23 Jul 2026 00:00:00 +0000

is-a.dev provides subdomains for eligible personal and non-commercial development-related sites, with registration and changes reviewed through GitHub pull requests.

This blog also lists zjy.is-a.dev as an address. My register repository is a fork of is-a-dev/register. After approval, the domain still needs to point to the site and be bound in the hosting platform; registration alone does not finish setup.

Figure 1: The is-a.dev project banner, taken from the registration repository.

Start with a real site

The official Quickstart asks for a sufficiently complete, eligible site before applying. Read the current requirements and terms first; a domain request is not a substitute for having a site to point to.

Registration rules can change. Check the official documentation and upstream repository before filling in the JSON file and opening a pull request.

Make a reviewable request

The basic path is to fork the upstream registration repository, add the appropriate JSON file under domains/, and open a pull request. The filename represents the requested subdomain.

Keep the official PR template, provide the requested site context, and respond to review comments. A local commit or a successful push to your fork does not mean registration has been approved.

Maintainers check the site and configuration, and merge times vary. Check each JSON field and destination; respond to requested changes in the same pull request.

Prepare a concrete GitHub Pages request

Suppose your GitHub username is yourname and you want yourname.is-a.dev. In your fork, create domains/yourname.json. This follows the official GitHub Pages example; replace both the account and destination with your own details:

{
  "owner": {
    "username": "yourname"
  },
  "records": {
    "CNAME": "yourname.github.io"
  }
}

The filename requests the subdomain, owner.username identifies your GitHub account, and records.CNAME names the website host. Those are different roles. Do not put an article URL in the owner field or use a repository’s GitHub webpage as the hosting target. Use ordinary double quotes, no trailing comma after the final field, and no comments inside JSON.

Check the upstream directory for an existing name and read the current naming requirements. yourname is a placeholder, not a claim of availability. Make the original website address work first, with recognizable content and navigation, so the request points to a site reviewers can evaluate.

Open the request against upstream

After saving, inspect the diff for only the intended domain file. Use GitHub’s Contribute → Open pull request flow and check the destination: the base repository should be is-a-dev/register, while the source is your fork. A request opened only against your own fork does not enter upstream review.

Retain and complete the PR template with the site link and screenshot. Show a usable page rather than an empty placeholder. Requests are public, so use public-facing contact information and keep credentials or unrelated personal information out of the description.

For requested changes, update the same branch so the existing PR updates. Match the comment to the relevant line and field before editing. A small correction does not need a duplicate application. Automated checks can confirm requirements such as formatting; acceptance still depends on maintainer review and merge.

DNS and redirects solve different problems

A DNS record helps a hostname reach the appropriate service. It does not normally contain a browser path such as /zh/, and a CNAME target is a hostname rather than a full HTTPS URL.

A URL redirect instead sends the browser to another address, potentially including a path. The official FAQ explains that is-a.dev’s URL option is a custom redirect mechanism rather than a normal DNS record.

For example, to serve a GitHub Pages site directly at name.is-a.dev, configure DNS and bind the domain in Pages. To send visitors to an existing /zh/ page instead, examine the official URL redirect option. Choose the outcome before filling a record so a webpage path does not end up in a CNAME.

Configure GitHub Pages as well

For a GitHub Pages setup, the official platform guide describes a CNAME target such as github-username.github.io. After the registration PR is merged, add the custom domain in the hosting repository’s Pages settings and enable HTTPS when available. If Hugo publishes the site automatically, keep the domain configuration in the source or build workflow so the next deployment preserves it.

Domain verification is another separate step and can involve a TXT record at a verification hostname. Do not combine unrelated record types at the same CNAME hostname simply because a host asks for verification; follow the provider-specific instructions.

Keep Hugo source and hosting settings aligned

The Hugo source repository and the repository serving GitHub Pages can be different. Configure the custom domain where the site is actually published, and edit Hugo’s site address in its source configuration. Identify those two roles before changing settings.

Check baseURL and how the deployment preserves domain configuration. If your publishing method needs a CNAME file, retain it in source that reaches the output or generate it during the build. A manual change only inside one public/ directory can disappear on the next build. The exact placement should follow your Pages deployment method.

Build normally after changing the address, then inspect both language homepages, articles, images, language switching, and feeds. A new domain does not require new article slugs. If some links still return to the old host, trace configuration and absolute body links before changing established paths.

Verify the result in layers

Check the merged registration, DNS resolution, hosting custom-domain setting, certificate, and actual page response separately. A 404, certificate error, and redirect loop indicate different stages of the setup.

For a bilingual blog, open both language paths and follow a few internal links. A working homepage does not establish that article links, feeds, and language switching all use the intended address.

Later updates and removal also go through the registration workflow. Keep the permanent host address usable while checking a new custom domain. For the site’s broader Hugo setup, see Liquid Stack; for current service requirements, return to the official documentation.

GitHub Pages on Jingyuan