Versioning the configuration: a history you can prove
An archive answers what changed and why; only the device says what is running now.

A baseline and an approval are governance objects; what carries them between changes is a versioned archive. Version control “is a system that records changes to a file or set of files over time so that you can recall specific versions later” (Git book, line 347). This sheet covers the mechanism — what is committed, what is kept out, what the messages and the revision marks are for — and the two things the archive cannot do: it is not the running device, and it is not by itself protected evidence.
What the history is asked to answer
A configuration archive answers four questions about every change — what changed, when, by whose hand, with what justification — and makes a previous state reconstructible. Version control offers “see who last modified something that might be causing a problem, who introduced an issue and when” (Git book, line 351). The configuration management guide states the same requirement: a baseline “can be changed only through change control procedures” (SP 800-128 lines 867–869), with a version number managed for each configuration item (line 2138). The change record and the approval are the governance sheets’ subject; what the archive owes them is the state they refer to.
What goes into the archive, and what stays out
Three artefacts are routinely confused; only two belong in the archive. The declared intent is a template, a playbook or a variable file; the rendered configuration is what a run would produce from it; the device state is what is actually running. The Ansible documentation puts the first under version control as the normal case — “you can write a playbook and put the playbook under source control. You can then use the playbook to push new configurations or confirm the configuration of remote systems” (line 21) — and a node can be told to fetch that repository itself (line 116). Rendered configuration earns its place when a person reads the difference before it is applied; device state changes without asking anyone.
declared intent rendered configuration device state
(template, playbook) (the build from it) (the device)
committed committed NOT committed
"what we meant" "what we built" "what we got"
history and diff prove the first two;
only collection from the device reaches the third.
Credentials and keys stay out entirely. How secrets are handled is the sibling sheet’s subject, on CLI automation and credential handling; what matters here is that the archive is a copy, read by people who should not acquire a password with it. The Git book’s instrument for exclusion is a pattern file named .gitignore, for files “you don’t want Git to automatically add or even show you as being untracked” (line 515, the name at line 517), and its worked example is generated build products. An ignore rule is a convenience, not a control.
The mechanics that carry the trace
Three mechanics carry the trace. The commit is the unit: commit “each time the project reaches a state you want to record” (Git book, line 343), because each commit “records the snapshot you set up in your staging area” (line 749) — anything left unstaged is not in the history (line 700). A commit bundling several changes makes the history unreadable, and a file edited after staging is committed in its older form — the tool “stages a file exactly as it is when you run the git add command” (line 481). The message joins the commit to the change record: the book’s own example carries an identifier from outside the commit, Story 182: fix benchmarks for speed (line 741). Revision marks give a named point to deploy from and separate lines of work to merge — the book’s contents name Tagging (line 51) and Basic Branching and Merging (line 65). The review before that merge is the approval act, which Cybersecurity Governance owns.
An archive is a record, not a witness
The first limit: the archive holds intent, not outcome. A device may be changed by hand, by a second tool, or by an emergency fix that never reached the repository; finding that gap means querying the device and its audit records for unauthorised change events (SP 800-128 line 2974), which belongs to this batch’s drift sheet. The second limit is that a history is not protected evidence. The guide says why an old baseline is kept: retention “allows for a rollback or restoration to a previous secure and functional version”, and “archiving previous baseline configurations is useful for incident response and traceability support during formal audits” (lines 2883–2886). But what makes a record usable as evidence — protected from modification, retained for a defined period, actually read — belongs to the L1 sheet on evidence and audit trails in Cybersecurity Governance, not to the tool. A single copy is a single failure: “whenever you have the entire history of the project in a single place, you risk losing everything” (Git book, line 385).
Where the process ends and the mechanism begins
What is versioned, and what a commit contains, is a mechanism decision, made here. What counts as a configuration-controlled change, which baseline is approved and who signs are decisions of the configuration-management and change-approval sheets in Cybersecurity Governance.
Level and prerequisites
L5 — specialist automation and operations. It assumes the sibling sheets on device APIs and on CLI automation and credential handling, plus the L1 vocabulary of a baseline and a configuration item. It prescribes no platform command and no repository layout.
Where to go next
References
- Git — Pro Git, 2nd Edition, “About Version Control” (project documentation, extracted page;
git-about-version-control.txt) — the definition of version control; what a history is used for; the single-copy failure. - Git — Pro Git, 2nd Edition, “Recording Changes to the Repository” (project documentation, extracted page;
git-recording-changes.txt) — the commit as a snapshot; the staging area; the exclusion pattern file; the example commit message; the contents entries for tagging and for branching and merging. - NIST — Guide for Security-Focused Configuration Management of Information Systems (SP 800-128, August 2011) — https://doi.org/10.6028/NIST.SP.800-128 — the approved baseline as the object that only change control may rewrite; the version number managed per configuration item; retention, rollback and traceability; the audit-record query for unauthorised change events.
- Ansible community documentation — “Ansible playbooks” (project documentation, extracted page;
ansible-playbooks-intro.txt) — the playbook placed under source control; the push of new configurations or the confirmation of existing ones; the pull-mode fetch of a configuration repository.