How to Present GitHub Change Management as Evidence for ISO 27001 and SOC 2

When an engineering team goes through an ISMS (ISO/IEC 27001) certification audit or a SOC 2 examination, change management is almost always on the list. All the code lives in GitHub and every change is reviewed. Even so, this is an area where teams often get stuck on what exactly to show, and how.

This article first sets out what auditors want to confirm about change management, then walks through the GitHub settings to put in place and how to keep the evidence.

What auditors want to confirm about change management

The relevant requirements are:

Neither says "configure GitHub this way." What matters is whether you can show, with records, that changes followed the procedure you defined.

In practice, the check usually goes like this:

1. You are asked for a list of changes that went to production during the observation period
2. The auditor samples several changes from that list
3. For each sampled change, they confirm that someone other than the author approved it before it reached production
4. For any emergency changes, they confirm that after-the-fact approval and records exist

So what you need is a list of changes covering the whole period, plus an approval trail for each change. If either one is missing, the explanation gets difficult.

Settings to put in place in GitHub

Before thinking about evidence, enforce the procedure itself through GitHub settings. Rather than only writing the rules in a document, make them impossible to break by design; that keeps the explanation during the audit short.

On the branch that goes to production (such as main), configure the following using branch protection or rulesets:

• Require a pull request before merging: closes the path where a direct push changes production code
• Require at least one approval: a change cannot be merged without approval from someone other than its author
• Dismiss approvals when new commits are pushed: prevents changes from being quietly added after approval
• Do not exempt administrators: if administrators alone can bypass protection, you can no longer say that "every change went through approval"
• Block force pushes (history rewrites) and branch deletion

Alongside this, your change management procedure should state which branch is production, and, for emergencies, who approves and how, and what must be recorded afterwards. Whether the settings match the written procedure is also something auditors look at.

Why screenshots are not enough

A common way to provide evidence is to take screenshots of pull request pages or the branch protection settings page and paste them into a document. This approach has structural weaknesses:

• It only shows a single moment. A screenshot of a settings page shows only that the setting was in place at the moment it was taken. If protection was turned off partway through the observation period and then turned back on, that fact will not appear
• The date and source are hard to verify. A date shown in an image is just part of the image; a third party has no way to confirm when or where it was captured
• Collecting it takes effort every time. Finding and capturing the right screen for each sampled change has to be repeated for every audit

Auditors themselves are increasingly asking for automatically timestamped, traceable records rather than manually gathered evidence like this.

Keeping a record across the whole period

There are two points:

1. Record changes at the moment they happen. Instead of gathering material right before the audit, record when, who and what at the time a push or pull request merge occurs. If you collect afterwards, you cannot capture anything that was deleted or changed in the meantime.

2. Keep the record in a form the audited organization cannot rewrite later. GitHub's event history and audit log are useful, but those records sit inside a system managed by the very organization being evaluated. Retention also has an upper limit, and depending on your plan it may not cover a 6 to 12 month observation period. It is worth checking the retention period for your own plan once.

To show that records have not been rewritten after the fact, a common technique is to chain each record's fingerprint (hash value) to the previous record. Rewriting a single record in the middle breaks every link after it, so any tampering can be detected.

What SPHIOR can and cannot do

SPHIOR's GitHub integration handles both of these points automatically:

• It records events such as pushes and the creation or merging of pull requests at the moment they occur
• Each record includes the event type, the actor, the time of occurrence, and a fingerprint of the full payload received from GitHub. The payload itself is not stored
• Records are sealed as a chain of linked fingerprints, so tampering can be detected. You can also export a verification pack and check it yourself

On the other hand, SPHIOR does not cover the following:

• The review approval action itself is not currently recorded. For approvals, use the branch protection settings described above to enforce that nothing can be merged without approval, and explain them with those settings and your written procedure
• It does not decide whether you pass or fail an audit. What SPHIOR provides is supporting evidence to show to your auditor

The free tier retains records for 90 days. When you need records for the entire observation period, you can switch to a plan with longer retention (Pricing).

Summary

• Change management reviews ask for the list of changes during the period and the approval trail for each change
• In GitHub, enforce approvals with branch protection and do not exempt administrators
• A screenshot only shows one moment. The reliable approach is to record events as they happen, in a form that cannot be rewritten

To avoid scrambling for screenshots right before an audit, the shortest path is to start recording well before the audit begins.