GitLab CI DNS Workflows

GitLab CI can run DNS changes safely when the pipeline has a hard boundary:

merge request = validate and preview
protected branch or environment = apply

This guide complements DNS in CI/CD Pipelines, GitHub Actions DNS Workflows, and DNS Automation.

For GitLab syntax details, keep the official GitLab CI/CD YAML reference, CI/CD variables documentation, and protected environments documentation nearby.

Repository Layout

Keep DNS easy to review.

dns/
  dnsconfig.js
  creds.example.json
  zones/
    example.com.js
 
terraform/
  dns/
    main.tf
    variables.tf
    versions.tf

Pick one source of truth per zone. Mixing Terraform, DNSControl, dashboard edits, and ad hoc scripts for the same record set creates drift.

GitLab Variables

Store DNScale credentials as GitLab CI/CD variables, not in .gitlab-ci.yml.

Recommended variables:

For production variables:

• mark them protected
• mark them masked if the value format allows it
• scope them to the production environment where possible
• avoid making them available to merge-request pipelines from untrusted sources

DNScale tokens should be zone-scoped where possible. A token for example.com should not be able to edit every zone in the account.

Pipeline Shape

Use stages:

stages:
  - validate
  - preview
  - apply
  - drift

Merge requests run validate and preview. The default branch runs apply. A schedule runs drift.

DNSControl Merge-Request Preview

This job checks DNSControl config and prints a preview in merge-request pipelines.

dnscontrol:preview:
  stage: preview
  image: golang:1.25
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - dns/**/*
        - .gitlab-ci.yml
  before_script:
    - go install github.com/StackExchange/dnscontrol/v4@latest
  script:
    - cd dns
    - dnscontrol check
    - DNSCALE_API_KEY="$DNSCALE_READ_TOKEN" dnscontrol preview

If the provider requires write-capable credentials for preview, do not run this job in untrusted merge-request contexts.

DNSControl Apply

Apply only from the default branch and attach the job to a protected environment.

dnscontrol:apply:
  stage: apply
  image: golang:1.25
  environment:
    name: production
    deployment_tier: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      changes:
        - dns/**/*
        - .gitlab-ci.yml
  before_script:
    - go install github.com/StackExchange/dnscontrol/v4@latest
  script:
    - cd dns
    - dnscontrol check
    - DNSCALE_API_KEY="$DNSCALE_PRODUCTION_TOKEN" dnscontrol push

Protect the production environment in GitLab so only approved maintainers or release roles can deploy.

Terraform Merge-Request Plan

For Terraform-managed DNS:

terraform:dns:plan:
  stage: preview
  image: hashicorp/terraform:1.9
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - terraform/dns/**/*
        - .gitlab-ci.yml
  variables:
    TF_IN_AUTOMATION: "true"
  script:
    - cd terraform/dns
    - terraform fmt -check
    - terraform init -input=false
    - terraform validate
    - DNSCALE_API_KEY="$DNSCALE_READ_TOKEN" terraform plan -input=false

If your Terraform state backend needs production credentials, decide whether merge-request plans are allowed to access that backend. If not, use a separate read-only plan path or restrict plans to trusted branches.

Terraform Apply

terraform:dns:apply:
  stage: apply
  image: hashicorp/terraform:1.9
  environment:
    name: production
    deployment_tier: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      changes:
        - terraform/dns/**/*
        - .gitlab-ci.yml
  variables:
    TF_IN_AUTOMATION: "true"
  script:
    - cd terraform/dns
    - terraform init -input=false
    - DNSCALE_API_KEY="$DNSCALE_PRODUCTION_TOKEN" terraform apply -input=false -auto-approve

For high-risk zones, avoid fully automatic apply. Use protected environments, required approvals, or a manual job:

  when: manual
  allow_failure: false

Scheduled Drift Checks

GitLab schedules can run a non-mutating drift check.

DNSControl:

dnscontrol:drift:
  stage: drift
  image: golang:1.25
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
  before_script:
    - go install github.com/StackExchange/dnscontrol/v4@latest
  script:
    - cd dns
    - DNSCALE_API_KEY="$DNSCALE_READ_TOKEN" dnscontrol preview

Terraform:

terraform:dns:drift:
  stage: drift
  image: hashicorp/terraform:1.9
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
  variables:
    TF_IN_AUTOMATION: "true"
  script:
    - cd terraform/dns
    - terraform init -input=false
    - DNSCALE_API_KEY="$DNSCALE_READ_TOKEN" terraform plan -detailed-exitcode -input=false

With terraform plan -detailed-exitcode, exit code 2 means changes are present. Treat that as a drift signal that needs review.

Rollback

Rollback should use the same path as the original change:

git revert <bad-commit>
git push

Then let the pipeline validate, preview, apply, and verify. For migrations, prepare the rollback commit before the change window begins.

Guardrails

Use these rules for production DNS:

• Merge requests preview DNS changes but do not mutate production.
• Production apply jobs run only from protected branches or protected environments.
• DNScale production tokens are protected, masked, and environment-scoped.
• Each token is scoped to the minimum set of zones.
• Drift jobs alert; they do not automatically overwrite manual changes.
• DS, DNSKEY, NS, MX, CAA, and apex changes require extra review.

Related Guides

• DNS Automation
• DNS Operations
• DNS in CI/CD Pipelines
• DNS as Code Best Practices
• Managing DNS with Terraform
• Managing DNS with DNSControl