Repository audit and monitoring — who changed what, when

Git history answers “what changed in the files”. It is silent on every question this part has been about: who was granted admin, when branch protection was relaxed, which token was minted and by whom, who bypassed push protection, and which repository was made visible outside the organisation. Those events exist only in the forge audit log, and if you have not arranged to keep it, the answers are gone by the time anyone asks.

Two records, two questions

flowchart TD
    A["change to production"] --> B{"what kind of change?"}
    B -->|"file content"| C["git log, commit, PR, review"]
    B -->|"permission or setting"| D["forge audit log only"]
    C --> E["reproducible from the repository"]
    D --> F["retained by the forge, until it is not"]
    F --> G["streamed to your own store"]
    G --> H["timeline survives the forge account"]

The asymmetry matters during an incident. The commit side of the timeline is durable, distributed, and verifiable from any clone. The settings side lives in one place, is retained for a bounded period, and is administered by exactly the accounts you may be investigating.

The event classes worth watching

Not every audit event is interesting. These are:

• Protection changes. A branch protection rule created, edited, or deleted; a required check removed; bypass allowance granted.
• Role and membership changes. A member promoted to admin or owner, an outside collaborator added, a team’s repository permission raised.
• Credential events. A personal access token created, a deploy key added, an app installed with write scope, an SSH key registered.
• Visibility and lifecycle. A repository made public, transferred, archived, or deleted; a fork created outside the organisation.
• Control overrides. Push protection bypassed, a required review dismissed, a merge performed by an administrator past a failing check.

ORG=example-org
gh api "/orgs/$ORG/audit-log?phrase=action:protected_branch" \
  --paginate --jq '.[] | [.created_at, .actor, .action, .repo] | @tsv'

The phrase parameter takes the same query syntax as the web view, so the filters you develop interactively are directly reusable in a script.

From log to detection

A log that is queried only after an incident is a forensic artefact, not a control. The conversion is a short alert list - short, because alert fatigue destroys the capability faster than not having it:

1. Branch protection disabled or weakened on any repository in the production set. Page, do not email.
2. A new organisation owner or repository admin. This should be rare enough that every occurrence is checked.
3. Push-protection bypass. Real time, with the actor and the stated reason in the notification.
4. Repository visibility changed to public. Immediate, irrespective of intent.
5. A token or deploy key with write scope created outside the provisioning process. Compare against the expected set rather than alerting on every creation.

Reconstructing a timeline

When something has gone wrong, the reconstruction interleaves both records:

• From Git: the commit, its author and committer dates, its signature status, the pull request, the reviewers, and the merge commit’s parents.
• From the audit log: the settings state at the time, any protection change immediately before the merge, the identity that performed it, the IP and client, and any token creation preceding the push.
• From CI: which run produced the artefact, from which commit, and with which credentials.

The question that catches teams out is “was the control in place at the time?” - and it is answerable only from the audit log, because a settings page shows the present, and the present is what the incident has already changed.

Production discipline

1. Stream before you need it. Retention is finite and the gap is unrecoverable; this is a one-day task that is only ever done too late.
2. Alert on control changes, not on activity. Pushes and merges are noise; a protection rule being weakened is signal.
3. Review the override log monthly. Bypasses, dismissed reviews, and admin merges past failing checks are the three numbers that describe whether your controls are real.

Cross-course references

• Observability for Production Engineers - the log pipeline parts cover shipping, retention, and alerting on exactly this class of event.
• Linux for Production Sysadmins - auditd and remote syslog solve the same problem at host level, including the same requirement to ship off-box.
• Kubernetes for Production Engineers - the cluster audit log is the downstream half of this timeline, and the two must be correlated to trace a change end to end.

Quiz