The change record — the artefact that survives the change

The change record is the artefact that survives the change. When the deploy is finished, the pipeline green, the on-call rotation changed, the change record is what an auditor reads six months later. The record is not a wiki page. The record is not a Slack thread. The record is an issue, a pull request, a discussion, and a merge commit - all in Git, all queryable, all signed.

A wiki page drifts because no one is responsible for keeping it current. A Slack thread drifts because it is impossible to query. Git is the only system the team already operates that is durable, queryable, signed, and survives the engineer who wrote the change.

The four components of a change record

A change record has four components. Each lives in Git; each plays a different role.

flowchart LR
    I["Issue: motivation and acceptance criteria"] --> P["Pull request: change and review"]
    P --> D["Discussion: design and trade-offs"]
    D --> M["Merge commit: decision and timestamp"]
    M --> A["Audit: walkable history"]

• Issue. Motivation and acceptance criteria. Why the change exists, what “done” means, who is affected. Lives in the issue tracker; links to the PR.
• Pull request. The change and the review. The diff, the approvers, the CI runs, the comments. The PR is the operational artefact; the issue is the motivation.
• Discussion. The design and the trade-offs. Inline review comments, design documents, alternatives considered and rejected. Lives in PR comments and linked documents.
• Merge commit. The decision. Records who merged, when, with what commit message, on what branch.

The four components together answer the auditor’s and the operator’s questions. Separated, each is a fragment.

Why the change record survives

Git is content-addressed and immutable. A commit SHA is the identity of the change; the commit cannot be edited, only amended or reverted. GitHub and GitLab keep the PR, the diff, and the comments as historical records even after merge.

The practical test: given a deployment annotation that records a commit SHA, can an auditor walk from the deployment back to the change record? The chain is deployment, annotation, commit, PR, issue, ticket, rationale. Every link is a foreign key. A broken link is an audit gap.

COMMIT=8a3f9d2
REPO=acme/infrastructure
gh pr view "$COMMIT" --repo "$REPO" \
  --json number,title,body,author,reviewDecision,mergedAt
# returns the PR that introduced the commit, including
# the title, body, author, review decision, and merge
# timestamp - the four components of the change record

The merge itself is part of the record:

PR=1234
gh pr merge "$PR" --squash --delete-branch \
  --subject "Add IRSA binding for checkout S3 access (#$PR)" \
  --body "Squash-merged via change record #$PR. Audit
chain: issue #1234 -> PR #$PR -> commit $COMMIT ->
deploy pipeline -> Deployment annotation."

The --squash flag collapses the change into a single commit on the base branch; --delete-branch removes the feature branch; the --subject and --body arguments preserve the change record’s identity in the squash commit. A wiki page that records the same information cannot be queried by commit SHA. The change record’s advantage is its addressability.

Designing the change record template

The template is the gate. A change record that does not match the template is a change record that does not merge. Each section is a required field; branch protection enforces it; the merge button is disabled until each section is filled.

flowchart TB
    T["Change record template"] --> S1["What section"]
    T --> S2["Why section"]
    T --> S3["When section"]
    T --> S4["Who section"]
    T --> S5["Where section"]
    T --> S6["How section"]
    T --> S7["Refs: ticket and design doc"]

TITLE="Add IRSA binding for checkout S3 access"
BODY=$(cat <<'EOF'
## What
Adds IRSA annotation to checkout service-account.

## Why
Required for new S3 read path introduced in #1234.

## When
Window: 2026-08-22 02:00-04:00 UTC.

## Who
Author: alice; Approver: bob.

## Where
Cluster: payments-prod; namespace: checkout.

## How
Apply with Argo CD sync; verify IAM role session via
aws sts get-caller-identity; rollback via revert.

Refs: #1234, design-doc/2026-08-irsa.md
EOF
)
gh pr create \
  --title "$TITLE" \
  --body "$BODY" \
  --base main \
  --head feat/checkout-irsa \
  --reviewer bob,carol \
  --label "change,iam,production"

A template that requires the seven fields - the six questions plus the refs - produces a change record that survives the change.

Production discipline

1. The change record is in Git. Issues, pull requests, comments, commits. Wikis and Slack threads are not the record.
2. The template is enforced. A PR that does not match the template does not merge; branch protection is the enforcement.
3. The merge timestamp is the “when”. Not the PR open, not the first commit, not the deploy - the merge commit.

Cross-course references

• This course, Part LXIV (Auditability) - the five-question audit the change record answers.
• This course, Part XLVIII (Conditional deploys)
  • environment protection rules that gate the change record at apply time.
• Linux for Production Sysadmins - Parts XXXIII (ChangeMgmt) cover the change-management process that produces the issue side of the change record.

Quiz