CNX Documentation

Managing zone changes

Changes to your DNS zones are made by editing files in the zones repository and opening a merge request. Validation runs automatically on every push, completing within about 30 seconds and posting the result as a status check. Once a Checker merges the request, deployment is automatic too — the change is live within about 120 seconds.

Before starting, clone the repository using Getting started and confirm your role using Identity and access.

The change workflow

  1. Start from the current main branch and create a branch for your change.
  2. Edit the configuration, commit it, and push the branch.
  3. Open a merge request on CNX's Git server.
  4. Review the validation status. If it fails, push a correction to the same branch; validation runs again automatically.
  5. A Checker reviews the diff and successful validation, then approves and merges the request.
  6. Check the deployment result. A removal follows the grace period described below; other accepted changes deploy automatically.

Before creating each new branch, update your local copy:

git switch main
git pull --ff-only

The examples below cover adding, updating, and removing a zone. After each push, complete the merge-request and Checker steps above.

Adding a zone

Create a new directory named after the zone apex, with a zone.conf inside it, using the template in zone.conf format as your starting point.

To try this out before touching a real zone, do it once with example.com exactly as shown below — the platform recognizes this specific name, runs it through the same validation as any real zone, and never deploys it.

git switch -c add-example-com
mkdir example.com

Edit example.com/zone.conf:

  • Set $ORIGIN to example.com.
  • Update the SOA hostmaster to match contacts.yaml
  • Add your records
git add example.com/zone.conf
git commit -m "add zone example.com"
git push origin add-example-com

When you're ready to add a real zone, repeat these steps with your own domain name instead. Once the zone deploys, check the reports repository (where your subscription includes it) — a new zone gets its own DNSSEC key automatically, and its first DS record will be waiting for you to publish at your registrar. See Publishing and updating DS records.

Making a change

The same flow applies to any change to an existing zone — for example, adding a record:

git switch -c add-vpn-record

Open the zone's zone.conf in your editor and add your record(s), for example:

vpn  IN A  203.0.113.50
git add example.com/zone.conf
git commit -m "add vpn A record for example.com"
git push origin add-vpn-record

Removing a zone

To decommission example.com in CNX's DNS service, update delegation at your registrar or parent zone first. Point example.com to the nameservers for the new DNS provider. Delegation is what takes CNX out of the resolution path for users.

Then remove the zone from the zones repository:

git switch -c remove-example-com
git rm -r example.com
git commit -m "remove zone example.com"
git push origin remove-example-com

Open a merge request for the branch. After a Checker approves and merges it, CNX's deployment pipeline detects that the zone directory has been removed and posts a comment on the merge request confirming that the zone is scheduled for removal, including the exact date and time.

Twenty-four hours after that scheduled time, the zone is permanently removed from CNX's authoritative nameservers.

The zone file is always named zone.conf, and CNX's NS records at the top of it shouldn't be modified — see zone.conf format for the full template. If a name needs to point at a CDN, SaaS platform, or anything else that only gives you a CNAME, use aliases.yml to flatten it — it works for any record, not just the apex.