How to Register a Free .is-a.dev Subdomain: Complete GitHub Guide

To register a free .is-a.dev subdomain, fork the is-a-dev/register repository, create a JSON file describing your subdomain in the domains/ directory, and submit a pull request that triggers automated DNS deployment.

The is-a-dev project provides free subdomains under the .is-a.dev namespace for developers and personal projects. Unlike traditional domain registrars, registration is handled entirely through GitHub, making the process transparent, auditable, and version-controlled. This guide walks you through how to register your free .is-a.dev subdomain by contributing to the open-source repository.

Step-by-Step Registration Workflow

Fork the Repository

Start by creating your own fork of the is-a-dev/register repository on GitHub. This gives you a personal copy where you can add your subdomain configuration.

According to the project documentation in README.md at line 32, forking is the first step before adding any domain files.

Create Your Domain JSON File

In your forked repository, create a new file inside the domains/ folder. The filename (without the .json extension) becomes your subdomain. For example, myname.json creates myname.is-a.dev.

The JSON file must follow the structure defined in existing entries such as domains/0xbit.json (lines 1-8):

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

You can create this file using Git commands:

git checkout -b add-myname
echo '{
  "owner": { "username": "your-github-username" },
  "records": { "CNAME": "your-github-username.github.io" }
}' > domains/myname.json
git add domains/myname.json
git commit -m "Add myname.is-a.dev"
git push origin add-myname

Submit a Pull Request

Push your branch to your fork and open a Pull Request (PR) against the upstream is-a-dev/register repository. The README explains that maintainers will review your submission and may request changes (see README.md lines 34-36).

The PR triggers automated validation tests defined in tests/domains.test.js (lines 70-104), which enforce rules such as unique single-character subdomains, proper parent ownership, and absence of conflicting NS records.

DNS Propagation

Once a maintainer approves and merges your PR, the repository's automated workflow regenerates the DNS configuration. According to README.md line 36, Cloudflare updates the DNS zone within a few minutes, making your new subdomain reachable.

Technical Architecture Behind Registration

DNS Generation Pipeline

The repository uses DNSControl to manage Cloudflare DNS records. The dnsconfig.js script scans the domains/ folder at build time using a glob call (lines 5-15) and loads each JSON file.

For CNAME records, the script transforms the JSON into DNS entries using the ALIAS function. As implemented in dnsconfig.js lines 51-54:

if (data.records.CNAME) {
    records.push(ALIAS(subdomainName, data.records.CNAME + ".", proxyState));
}

Reserved and Restricted Names

Certain subdomains are blocked from public registration. The util/reserved.json and util/internal.json files contain lists of names that cannot be claimed. The DNS script adds placeholder records for these reserved entries (see dnsconfig.js lines 38-45 and 64-68) to prevent conflicts.

Public API Generation

The util/raw-api.js utility aggregates all domain definitions into a versioned JSON API (raw-api/v2.json). This allows external tools to query registered domains programmatically (lines 14-30).

Summary

• Fork the is-a-dev/register repository to your GitHub account.
• Create a JSON file in domains/ where the filename is your desired subdomain (e.g., myname.json becomes myname.is-a.dev).
• Configure owner information and DNS records (CNAME, A, MX, or TXT) following the structure in domains/0xbit.json.
• Submit a pull request; automated tests in tests/domains.test.js validate your submission against project rules.
• Wait for merge and DNS propagation; Cloudflare updates the zone within minutes after approval.

Frequently Asked Questions

How long does it take to register a free .is-a.dev subdomain?

The registration process typically takes a few minutes to several hours, depending on maintainer availability. Once your pull request is merged, DNS propagation through Cloudflare happens within minutes, making your subdomain accessible almost immediately.

What DNS record types are supported in the domain JSON?

The system supports multiple record types including CNAME, A, MX, and TXT records. The dnsconfig.js script processes these entries and generates corresponding Cloudflare DNS records using DNSControl syntax.

Can I register multiple .is-a.dev subdomains?

Yes, you can register multiple subdomains by creating separate JSON files for each desired name. However, the validation tests enforce specific rules about single-character domains and parent ownership to prevent abuse and naming conflicts.

Why was my subdomain name rejected?

Submissions may be rejected if the name appears in util/reserved.json or util/internal.json, conflicts with existing domains, or violates testing rules in tests/domains.test.js. Names that impersonate official services or use restricted terms are automatically blocked by the validation pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}