infrastructure/dnscontrol-template
Watch
1
0
Fork
You've already forked dnscontrol-template
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
dnscontrol-template is a public starter template for DNS-as-Code with DNSControl: It includes multi-domain dummy configs, a safe CI workflow (automatic check/preview, manual push only), secret-based authentication (DESEC_API_TOKEN), and a README that documents the full workflow for adapting it to your own domains.
4 commits 1 branch 0 tags 30 KiB
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Paul 99ef789282 Merge pull request 'fix/node-before-checkout' (#1) from fix/node-before-checkout into main 
Reviewed-on: https://codeberg.org/paul2212/dnscontrol-template/pulls/1
2026-02-15 14:28:17 +01:00
.forgejo/workflows Restore auto DNS push on main 2026-02-10 21:56:00 +01:00
.gitignore Initial template release 2026-02-10 21:12:00 +01:00
creds.json.example Initial template release 2026-02-10 21:12:00 +01:00
dnsconfig.js.example Initial template release 2026-02-10 21:12:00 +01:00
LICENSE Initial template release 2026-02-10 21:12:00 +01:00
README.md Initial template release 2026-02-10 21:12:00 +01:00

README.md

DNSControl Template (deSEC + Forgejo Actions)

This repository can be published as a reusable template for DNS-as-code using DNSControl.

What is included

  • dnsconfig.js.example: starter DNS config with dummy values.
  • creds.json.example: credentials file using environment variable injection.
  • .forgejo/workflows/push.yml: CI workflow for validation/preview and manual apply.

Quick start

  1. Copy and customize the DNS config: 
    cp dnsconfig.js.example dnsconfig.js
  2. Copy credentials template: 
    cp creds.json.example creds.json
  3. Export your API token locally: 
    export DESEC_API_TOKEN="your-token"
  4. Validate and preview: 
    dnscontrol check
dnscontrol preview
  5. Apply changes when ready: 
    dnscontrol push

Forgejo workflow

The workflow in .forgejo/workflows/push.yml is split into two safe stages:

  • validate-and-preview:

    • Runs on pull_request and push to main
    • Executes dnscontrol check
    • Executes dnscontrol preview only if DESEC_API_TOKEN is available

  • push-dns:

    • Runs only on manual trigger (workflow_dispatch)
    • Executes dnscontrol push
    • Fails if DESEC_API_TOKEN is missing

Codeberg Actions setup

If you host this repository on Codeberg, make sure Actions are enabled in Settings -> Units for the repository. For CI jobs, it is recommended to use your own Forgejo Actions Runner. Reference: https://docs.codeberg.org/ci/actions/

Secrets setup

Set this repository secret in GitHub or Forgejo:

  • DESEC_API_TOKEN: required API token for your deSEC account

creds.json and dnsconfig.js are ignored via .gitignore, so real credentials and production records stay local.

Suggested publishing flow

  1. Keep your personal production records in private branches or private repos.
  2. Keep public template content generic (example.com, test IP ranges).
  3. Open PRs for DNS changes and review dnscontrol preview output.
  4. Trigger manual workflow dispatch only when changes are approved.

Provider support

DNSControl supports many more DNS providers than deSEC. It is also possible to manage and push changes to multiple providers in parallel from one config. See the official provider list: https://docs.dnscontrol.org/provider/index

AI Assistance Notice

Parts of this project were created or refined with AI assistance. All generated changes should be reviewed and tested by a human maintainer before release.

License

This repository uses the MIT License (see LICENSE).