Tip

You can also use the website to guide you in registering the subdomain, start by going to the search page

Note

TLDR:

Fork the repository
Make a JSON file in the /domains/<apex_of_choice> directory
Fill in your records as per our reference documentation
Make a PR and wait for a maintainer to merge it
After merge, wait ~24 hours for DNS to propagate
???
Profit. Enjoy your new subdomain!

Quickstart Guide

This is a short and concise tutorial on how to create a pull request with your desired DNS records on a subdomain. Note that we have requirements and standards for whatever content you host on your subdomain. Please refer to the Terms of Service.

Forking the repository

Head over to our registration repository and fork it to your GitHub account. Alternatively, you can click here to fork the repository.

Creating the subdomain file

Now in your fork, head into the domains/<apex> directory where <apex> is the apex domain where you want to register a subdomain. Now create a new file named <subdomain>.json where <subdomain> is the name of your desired subdomain. Please note that we have file name requirements. Please refer to the documentation.

Here's what a valid file path looks like for satr14.is-my.id:

domains/is-my.id/satr14.json

Setting your records

Next, you'll need to write your DNS record in our JSON schema. You can find this in the documentation. Please make sure your JSON is valid and properly formatted.

Tip

While our CI does it automatically for you, it's still a good practice to prettify your JSON before committing. Makes it easier for PR reviewers to read and understand your records.

Here's what a valid file would look like for Cloudflare pages:

{
  "owner": {
    "username": "satr14washere"
  },
  "records": {
    "CNAME": "steve.pages.dev"
  }
}

After you finish writing, commit your changes to a new branch and start a pull request. You can do this by clicking on "Commit changes..." > selecting "Create a new branch for this commit and start a pull request" > "Propose changes".

Opening a pull request

Now you should be in the "Comparing changes" page. From here, click on "Create pull request".

Caution

Please make sure to fill in the PR template checklist and website preview/subdomain purpose description. Failure to do so will result in your PR getting closed.

After a while, a maintainer will review and merge your PR. It may take a while for GitHub Actions to deploy your subdomain and for Cloudflare to propagate your DNS records. You can check the Actions tab to see if your subdomain is deployed.

Your subdomain is now live!

If you have any questions then feel free to reach out via GitHub discussions or open an issue.