GitHub change management beyond required reviews
Required pull request reviews are where most GitHub teams start with change control. Rulesets, required status checks, CODEOWNERS and merge queues take it further, and together they can make a protected branch hard to change without review. What they do not provide by themselves is a change approval: a decision made in the organisation's change process, recorded in a tracker, and enforced at the merge button. This guide covers the GitHub features first, then shows where a change approval fits.
Rulesets
A repository ruleset is a named set of rules that applies to chosen branches. Rulesets can be switched between active and disabled, they can name actors allowed to bypass them, and several rulesets can target the same branch: when they do, their rules add up and the strictest applies. On private repositories, rulesets need GitHub Team (or Pro) or Enterprise.
Rules commonly used for change control include:
- Restrict deletions and Block force pushes, so a branch's history cannot be removed or rewritten;
- Require a pull request before merging, with its own options for required approvals, dismissing stale approvals when new commits are pushed, requiring review from code owners, and requiring approval of the most recent reviewable push by someone other than the person who pushed it;
- Require status checks to pass, naming the checks that must succeed;
- Require signed commits and Require linear history.
Classic branch protection rules offer a similar set of options. Rulesets are the newer mechanism and can be layered.
Required status checks
A required status check names a check that must report success on the pull request's head commit before it can merge. Two details matter for change control:
- Who may report it. A required check can be tied to a specific GitHub App as its source. Without that, any integration that can post a check or commit status with the same name could satisfy it.
- Which commit it is for. Checks belong to a commit. A new push starts with no checks on its new head, so required checks hold the merge until they run again.
That second detail is what makes a status check a natural place for an outside decision: it is commit-bound by design.
CODEOWNERS
A CODEOWNERS file maps paths to owners, who can be users or teams. With review from code owners required, a pull request that changes owned files needs an approving review from an owner of each. GitHub reads the file from .github/, the repository root or docs/.
Merge queues
A merge queue groups pull requests that are ready to merge, builds a temporary branch for each group with the target branch and the pull requests ahead of it, and asks the required checks to pass on that group's commit before merging. Workflows that should run in the queue listen for the merge_group event. The queue keeps the branch green when many pull requests merge in a short time.
What these features answer, and what they do not
Together these features answer: who reviewed the code, which checks passed, and whether the branch could be changed another way. A change management process usually adds questions of its own:
- Was this change approved through the change process, by the people the organisation names for that kind of change?
- Does a documentation fix take the same path as a database migration, or a lighter one?
- Can an emergency merge now and be reviewed within a deadline?
- Was the approval in the tracker made by someone allowed to make it, and not by the author?
- Which version of the rules decided this change, and can it be shown for every change in a quarter?
These are the questions a Merge Pilot change policy answers. The answer reaches GitHub as one required status check.
Where a change approval fits
On GitHub, Merge Pilot works as a GitHub App. When a repository is put under change management, it writes one ruleset, Merge Pilot change management, after showing the steps and asking for consent:
| Step | Ruleset rule | Required |
|---|---|---|
| Ruleset with Merge Pilot's required check | "Require status checks to pass" with Merge Pilot / change approval, from the connection's App only, on the target branches, without requiring branches to be up to date | Yes |
| Require a pull request | "Require a pull request before merging", with no reviews required by it | No (on by default) |
| Block force pushes | "Block force pushes" | No (on by default) |
| Block branch deletion | "Restrict deletions" | No (on by default) |
The check is the merge gate. Merge Pilot reports it on each pull request's head commit: success when the change policy is met, in progress while something is pending, failure when an enforced control failed. Because it is accepted from the App only, no other App or person can satisfy it. See What Merge Pilot writes to each repository and Merge gate on GitHub.
The ruleset is separate from yours. Rulesets you already have, with their required reviews, CODEOWNERS and other checks, stay as they are, and the rules add up on the branch. Bypass actors that an administrator adds to Merge Pilot's ruleset are kept, and the setup warns how many there are.
What the check stands for
The check's conclusion is the result of the whole change policy for that commit: the change approval in Jira or the built-in tracker, plus the controls the policy enforces, such as CI, code review, work items, secret and dependency scans. The check run's title names the first control that failed or is still pending, and its summary lists the policy and one line per control.
| What the policy needs | How it reaches GitHub |
|---|---|
| A normal change, waiting for approval or for a control still running | Check in progress |
| Approved, every enforced control passed | Check concludes success |
| Rejected, or an enforced control failed | Check concludes failure |
| A new commit pushed | No check on the new commit until Merge Pilot decides |
Required reviews and the change approval side by side
Required reviews and a change approval are different decisions, and a policy can ask for both:
- Code review in the policy counts each reviewer's latest Approve review, but only when it was given on the head commit, from someone with at least the chosen repository role, never the author, Merge Pilot or a bot. A later Request changes can hold the merge. See Code review.
- Change approval is decided in the tracker or in Merge Pilot by the people the policy's Who must approve names: the project's approver roles, approver pools, or the code owners of the changed files read from the same CODEOWNERS locations GitHub uses. Code owners are asked as people (
@login); teams are not asked and are listed as Not asked from …. See Code owners.
If GitHub's required reviews already cover peer review for you, leave them on and keep the policy's code review off or in report mode; the change approval then adds only the change-process decision.
Which checks a policy trusts
The policy's CI control reads runs on the pull request's latest commit, and it is explicit about their source:
- GitHub Actions workflow runs always count.
- Checks from another GitHub App count only when that App's slug is listed under Also count checks from these GitHub Apps. A check of the same name from another App does not count.
- Commit statuses count only with Count commit statuses on, because anyone who may push can post one.
- Merge Pilot's own check is never counted.
Runs left out for their source are named in the control's message. See Which runs count.
Merge queues with a change approval
When a pull request enters the merge queue, GitHub asks for the required checks on the merge group's commit. Merge Pilot answers with Merge Pilot / change approval on that commit. It passes only when change management approved the pull request at the commit it was queued with, and fails when Merge Pilot does not know the pull request, when its last decision is for another commit, or when that decision was not Can merge. The queue therefore never merges what change management did not approve. See GitHub merge queue.
Keeping the setup intact
Repository administrators can add bypass actors, disable a ruleset or remove a rule. Merge Pilot checks gated repositories for such gaps (a missing or unenforced ruleset, a missing rule that was chosen, bypass actors) when the company's branch protection check is on, and writes new gaps to the audit log as protection_weakened. Pushes that reach a covered branch without a pull request, force pushes and deleted branches are recorded as direct changes. If an administrator merges past the gate, the merge is flagged as Merged without approval.
Rolling it out on GitHub
- Create the GitHub App from its manifest, or use an existing one, and install it on the organisation's repositories. GitHub Enterprise Server 3.12 or newer is supported. See GitHub.
- Watch the repositories first. Nothing is written to a watched repository; Merge Pilot records what it would have decided.
- Write change policies, for example from the ITIL change management template, and try them with Which policy applies?.
- Move repositories to change management, choosing which optional ruleset rules to write.
- Keep your rulesets. Required reviews, CODEOWNERS and other required checks stay where they are; the change approval check is added next to them.
Next steps
The Merge gate feature page summarises the gate on GitHub and GitLab, and Setup steps and consent describes what is shown before anything is written. To see a change approval check on your own pull requests, ask for a demo.