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

> Learn how to register a free is-a.dev subdomain quickly. Fork the GitHub repository, create a JSON file, and submit a pull request for automated DNS deployment.

- Repository: [is-a.dev/register](https://github.com/is-a-dev/register)
- Tags: getting-started
- Published: 2026-03-09

---

**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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/myname.json) creates `myname.is-a.dev`.

The JSON file must follow the structure defined in existing entries such as [`domains/0xbit.json`](https://github.com/is-a-dev/register/blob/main/domains/0xbit.json) (lines 1-8):

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

```

You can create this file using Git commands:

```bash
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`](https://github.com/is-a-dev/register/blob/main/README.md) lines 34-36).

The PR triggers automated validation tests defined in [`tests/domains.test.js`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js) lines 51-54:

```javascript
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`](https://github.com/is-a-dev/register/blob/main/util/reserved.json) and [`util/internal.json`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/dnsconfig.js) lines 38-45 and 64-68) to prevent conflicts.

### Public API Generation

The [`util/raw-api.js`](https://github.com/is-a-dev/register/blob/main/util/raw-api.js) utility aggregates all domain definitions into a versioned JSON API ([`raw-api/v2.json`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/domains/0xbit.json).
- **Submit** a pull request; automated tests in [`tests/domains.test.js`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/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`](https://github.com/is-a-dev/register/blob/main/util/reserved.json) or [`util/internal.json`](https://github.com/is-a-dev/register/blob/main/util/internal.json), conflicts with existing domains, or violates testing rules in [`tests/domains.test.js`](https://github.com/is-a-dev/register/blob/main/tests/domains.test.js). Names that impersonate official services or use restricted terms are automatically blocked by the validation pipeline.