GitOps sounds like a tool. It is a rule: the desired state of the network lives in a repository, and the only way to change it is a reviewed commit.
Everything else — pipelines, diffing, drift detection — exists to make that rule safe.
The loop
edit → commit → review → CI validates → apply → verify → (drift detected?) → reconcile
The reverse direction matters as much: a nightly job compares the running configuration to the repository and reports differences. Manual changes are how the source of truth stops being true.
What goes in the repository
| Artifact | Example |
|---|---|
| Intent data | VLANs, subnets, WLANs, zones |
| Templates | Rendered per vendor |
| Policy | Validation rules |
| Inventory | Devices, sites, roles |
| Tests | Synthetic checks per site |
What does not go in: credentials, private keys, or anything that would be catastrophic in a public repo.
Secrets are the usual failure
A district repository that contains a PSK is one misconfigured visibility setting away from a public incident. Use a secret manager, environment variables in CI, or an encrypted file format — and rotate anything that was ever committed.
The pipeline
| Stage | Action | Blocks merge? |
|---|---|---|
| Lint | YAML, templates | Yes |
| Validate | Schema and policy | Yes |
| Render | Produce device config | Yes, on error |
| Diff | Show what would change | No, but reviewed |
| Deploy | Apply to canary, then fleet | After approval |
| Verify | Synthetic checks | Rolls back on failure |
A merge request that shows a five-line diff and a passing check is a change review that takes two minutes. That is the entire value proposition.
Drift detection
Nightly:
- Pull running configuration from every device.
- Render the expected configuration from the repository.
- Normalize both (order, whitespace, defaults).
- Report differences.
Normalization is where this project lives or dies. Device configs reorder lines, add defaults, and reformat timestamps. Compare a canonical form, not raw text.
Worked example: a WLAN change
- Branch: add a new SSID to
wlans.ymlfor one site. - CI validates the schema and checks the VLAN exists at that site.
- Diff shows two lines added.
- Review and merge.
- Pipeline applies to the canary AP group, runs a connect test.
- Applies to the site; a synthetic client associates and gets an address.
- Nightly drift confirms nothing else changed.
Rollback: revert the commit, merge, pipeline applies the previous state. That is a rollback anyone can perform at 02:00.
What breaks in production
- Manual changes in the UI, which the next pipeline run overwrites or reports as drift.
- No normalization, so the drift report is 400 lines of noise and gets ignored.
- Secrets in the repo, which is a rotation project waiting to happen.
- A pipeline that applies everything at once, so a bad commit is a district-wide event.
- No verification step, so "deployed" is confused with "working."
- Repository without owners, so nobody reviews and the rule becomes a suggestion.
Checklist
- The repository contains intent, templates, policy, and inventory.
- Every change is a reviewed merge request.
- CI blocks on lint, schema, and policy.
- Deployment is canary first, then batches.
- Verification runs after deploy and can roll back.
- Drift is detected nightly, against a normalized config.
- No secrets in history, and anything ever committed has been rotated.
Next
That completes the programmability series and the approved library. The natural next step is a set of learning paths that turn ninety articles into a curriculum.