The technical part of a governance programme is a week. The rest is why most of them fail.
A ruleset switched on without warning produces a support queue, a rollback, and an organisation that has learned to treat the next attempt as something to be resisted. That outcome is not caused by the policy being wrong — it is caused by the rollout.
The short answer
Section titled “The short answer”Measure before you enforce. Evaluate mode, or the audit log, tells you what a policy would have blocked. Guessing does not.
Announce before you enforce. Not after, and not the same morning.
Start with what everybody already agrees with. Credibility is spent, and the first policy should earn some rather than spending it.
Have a working exception path on day one. A policy with no exception route produces workarounds, and workarounds are worse than exceptions because they are invisible.
Measure afterwards. Whether behaviour changed, not whether the setting is on.
Measure first
Section titled “Measure first”Evaluate mode is the mechanism for rulesets. A ruleset in evaluate applies without enforcing, and GitHub describes it as letting you monitor which actions would or would not violate the rules. It is generally available and it removes the guesswork entirely.
For things without an evaluate equivalent — lifecycle policies, Actions settings — the audit log is the substitute. How often does the action you intend to restrict actually happen, and who performs it?
The number is almost always smaller than expected. “Nobody should be deleting repositories” turns out to be four deletions a quarter, all by two platform engineers. That changes the policy design: the allow list is obvious and nobody is inconvenienced.
Occasionally it is larger, and that is the more valuable finding — it means the practice you were about to prohibit is load-bearing, and you have discovered it before breaking anything.
Run it long enough. A week misses the release cycle. A rule that looks harmless on a Tuesday can block the quarterly release process, and that is exactly the failure that ends a programme.
The credibility budget
Section titled “The credibility budget”The concept that explains most of the guidance here.
A governance team has a finite amount of goodwill, and every policy spends some. A policy that is obviously sensible and cleanly rolled out spends very little and may even earn some back. One that breaks a release spends a great deal.
Which means the order matters more than the content. Three uncontroversial policies, well executed, build enough credibility that the fourth — genuinely contentious — is received as “they know what they are doing” rather than “here they go again”.
Reversed, the same policies fail. Leading with the contentious one, badly rolled out, means the three easy ones afterwards are resisted on principle.
Spend it on things that matter. A commit message format rule with no downstream consumer costs the same goodwill as a control preventing accidental public disclosure, and delivers nothing.
Earn it back by fixing things. A governance team that also removes friction — a faster repository creation path, a shared workflow that saves everybody effort, a CI improvement — is one whose next policy is received differently. This is not a trick; it is the difference between a team that constrains and a team that provides.
And by withdrawing when wrong. Admitting a policy did not work, and removing it, costs less credibility than defending it for two years.
Sequencing
Section titled “Sequencing”Start with rules nobody argues with. Block force pushes on default branches. Restrict deletions. Both are already defaults for good reasons, and enforcing them costs you nothing in goodwill.
Then the invisible ones. File size limits, path restrictions. Almost nobody is affected, and the ones who are get a clear, actionable message.
Then the ones with a stated reason. Required pull requests, required status checks. These affect everybody and they are defensible.
Leave the contentious ones until last, if at all. Signed commits, commit message formats, mandatory review counts. Each generates ongoing friction and each needs a downstream consumer to justify it.
One at a time. A rollout that changes five things simultaneously produces breakage nobody can attribute, and the attribution is what lets you fix the right thing.
Leave gaps between them. A month of quiet after each change is what lets the next one land as a normal event rather than as the fifth disruption this quarter.
Communication
Section titled “Communication”Announce with at least two weeks’ notice for anything that changes what developers can do.
Say what changes, not why it is good. Engineers respond to “from the 15th, pushes containing files over 25 MB will be rejected; here is how to handle large files instead”. They do not respond to a paragraph about governance maturity.
Include the workaround. Every announcement should say what to do when you hit the rule. An announcement that only says what is prohibited generates a support ticket per affected person.
Name the exception path. Who to ask, and how long it takes.
Tell them the reason in one sentence. Not a justification document — one sentence. “Files over 25 MB cannot be removed from history without invalidating every clone” is a reason people accept.
Send it where engineers actually read, which is rarely email. And send it twice: two weeks out, and the day before.
Follow up afterwards. What happened, how many were affected, what got fixed. This is the part everybody skips and it is what makes the next announcement credible.
Exceptions
Section titled “Exceptions”A policy with no exception path is a policy that generates workarounds.
The exception mechanisms available: bypass actors on a ruleset, allow lists on a repository policy, delegated bypass for lifecycle actions — both of the latter documented by GitHub as being in public preview and subject to change — and narrowing the targeting so a category is excluded.
Prefer targeting over bypass where the exception is categorical. If a class of repository genuinely needs different rules, express that as a property filter — visible in the policy, self-documenting, and automatically correct for new repositories in that class.
Use bypass for operational needs: automation that must push directly, break-glass access, migration work.
Restrict bypass to pull requests only where the mechanism allows, since it is a much narrower grant than direct push.
Time-bound exceptions. An exception with no end date is a permanent policy change made through the exception process.
Review the exception pattern. A rule with a steadily growing bypass list is a rule that does not match how people work, and the correct response is to change the rule.
And make the exception path fast. If getting an exception takes two weeks, teams will find another route, and you will not know about it.
Piloting
Section titled “Piloting”Between observation and enforcement sits a step that most rollouts skip and that resolves most of the risk.
Enforce for a few willing teams first. Not the whole estate — three or four teams who have agreed to it.
Choose teams that will tell you. A team that hits a problem and works around it silently teaches you nothing. A team that will complain loudly and specifically is the one you want.
Include a team with an unusual workflow. The pilot’s value is finding what you did not anticipate, and the median team does not surprise you.
Give it a real duration. Two weeks minimum, and long enough to include whatever their periodic processes are.
Then use them as advocates. A team that has lived with the policy and can say it was fine is far more persuasive to their peers than a central team asserting it.
And be willing to change the rule. A pilot that produces no changes was either a very good design or a pilot nobody engaged with. Usually the latter.
Pilots also produce the documentation. Whatever the pilot teams needed explained is exactly what the announcement should say — written by people who actually hit the problem rather than by whoever configured the policy.
Who to involve
Section titled “Who to involve”Governance imposed by a team nobody knows is governance that gets resisted on principle.
Find the engineers people actually listen to. Every organisation has them and they are rarely the most senior. If they think a policy is reasonable, adoption is straightforward; if they think it is bureaucratic theatre, nothing else you do matters.
Involve them before the design is finished, not at the announcement. A rule that was shaped by their input is a rule they will defend.
Give team leads advance notice before the general announcement, so they hear it from you rather than from a broken build. This costs one message and buys a great deal.
Have a decision forum. The genuinely contentious questions — should signed commits be mandatory, should deletion require approval — are not technical, and a platform team deciding them unilaterally is making organisational policy without a mandate.
Publish the reasoning. A short document per policy, stating what it requires and why, findable by somebody who hits the rule. Most resistance is to unexplained constraints rather than to the constraints themselves.
And close the loop with whoever asked for it. Policies frequently originate from a security or audit requirement, and the person who raised it should hear that it was implemented and what it cost.
What to do when it breaks something
Section titled “What to do when it breaks something”Fix it quickly, and publicly. A policy that blocks a release and takes four hours to resolve teaches the organisation that governance is a risk to delivery.
Have somebody available. Do not enforce a change and then go to a two-day offsite.
Decide in advance who can grant an emergency bypass, and make sure they are reachable.
Roll back rather than debate. If a policy is blocking real work and the fix is not immediate, turn it off, fix it properly, and re-enable. A rollback is a small embarrassment; a two-day outage is a programme-ending event.
Then find out why the observation period missed it. Every unexpected breakage is a gap in the measurement, and the answer is usually that the observation window did not cover a periodic process.
Record it. The list of things a policy broke, and how they were resolved, is what makes the next rollout better.
Measuring the outcome
Section titled “Measuring the outcome”Not “is the policy enabled”. That measures configuration.
Coverage. What fraction of repositories the policy actually applies to, including those that fall through targeting because a property is unset.
Violations prevented. How many pushes rejected, how many merges blocked. This is the number that justifies the work.
Bypass invocations, by actor and frequency. A rising trend means the policy is wrong.
Exception requests, and time to resolution. A slow path is a path being avoided.
Support volume attributable to the policy, which should spike and then fall to near zero. A persistent rate means the announcement was inadequate or the rule is wrong.
Behaviour change. For a file size rule, repository growth rates. For a required review rule, the proportion of changes reviewed. This is the outcome, and it is the one worth reporting upward.
Removing a policy
Section titled “Removing a policy”Less discussed than adding one, and it comes up more than expected.
Rules only aggregate. An enterprise ruleset cannot be relaxed from below, which means removing it removes the floor for everybody simultaneously.
Which makes removal riskier than it looks. Teams that relied on the enterprise policy for a control they never configured locally silently lose it.
Before removing, find out who depends on it. A rule that has been enforced for two years is part of how people work, and some teams will have stopped configuring the equivalent locally because they did not need to.
Announce a removal as you would an addition. “From the 15th, this will no longer be enforced centrally; if you need it, configure it at repository level.” Two weeks’ notice, same as anything else.
Consider narrowing instead. If the policy is wrong for some repositories, retarget it rather than removing it. That preserves the control where it works.
And record why. A policy removed without a documented reason will be reintroduced by the next administrator, who will assume its absence was an oversight.
The same applies to weakening. Relaxing a rule’s parameters — a size limit raised, a review count reduced — is a change to a control and deserves the same treatment as removing one.
When a policy fails
Section titled “When a policy fails”Not every rollout works, and recognising a failure early is better than persisting.
The signs:
A bypass list that keeps growing. The rule does not match how people work.
Exceptions granted routinely. Same signal, different mechanism.
Support volume that does not decay. The announcement did not work, or the rule is genuinely wrong.
Workarounds appearing. Repositories created outside the governed path, work moved elsewhere. The most serious signal, because it means the policy is being routed around rather than followed.
No measurable behaviour change. The policy is on, nothing is different, and the outcome metric is flat.
When you see these, the options are: narrow the targeting so it applies only where it works, change the rule to something people can comply with, or withdraw it.
Withdrawing is a legitimate outcome, and doing it deliberately preserves credibility. A policy quietly ignored for two years, with everybody knowing it is ignored, does more damage to a governance programme than one that was tried and withdrawn with a stated reason.
And it produces a finding. Why the policy did not work is usually more informative than the policy itself — it is telling you something true about how the organisation operates.
Common mistakes
Section titled “Common mistakes”Enforcing without observing. The single most common cause of failure.
A one-week observation window. It misses the release cycle.
Announcing after enforcing. People remember the surprise longer than the rule.
Starting with a contentious rule. Spends credibility you have not built.
Changing several things at once. Breakage nobody can attribute.
No exception path on day one. Produces invisible workarounds.
Exceptions with no expiry. Permanent changes through a temporary process.
Enforcing on a Friday or during a release. The blast radius is everybody.
Measuring configuration rather than behaviour. “The policy is on” is not an outcome.
Debating instead of rolling back. A blocked release is not the moment for a principled discussion.
A worked rollout
Section titled “A worked rollout”A file-size push rule, from decision to outcome, as a concrete example of the whole sequence.
-
The requirement. Repositories are growing because build outputs and large assets are being committed. A 25 MB push limit prevents the growth at source.
-
Measure. Look at recent large-file commits across the estate. Suppose the answer is: fourteen repositories have pushed a file over 25 MB in the last quarter, and eleven of those are one team’s design assets.
-
The finding changes the design. The design team has a genuine need, and the right answer for them is Git LFS rather than an exception. That is a conversation before the rollout, not a bypass after it.
-
Pilot. Enable it for three teams, including the design team once they have moved to LFS. Two weeks.
-
The pilot finds something. A release process attaches a large artifact via a commit rather than a release asset. Fix the process; add the finding to the announcement.
-
Announce. Two weeks’ notice, stating the limit, the date, what to do with large files instead, and who to ask. Sent where engineers read, and again the day before.
-
Enable, on a Tuesday morning, with somebody available.
-
Support. A handful of tickets in the first week, mostly people who had not read the announcement. The response is a link to the guidance.
-
Measure the outcome. A quarter later: rejected pushes per month, and repository growth rate compared with the previous year. The second number is the one to report.
Total elapsed time: about eight weeks for a change that takes ninety seconds to configure. That ratio is the point of this article.
And the highest-value step was step 2, which changed the design from “a rule with an exception” to “a rule plus a migration”, producing a better outcome for everyone including the team that would have needed the exception.
Mental model
Section titled “Mental model”A policy rollout is a change to how several hundred people work, delivered through a settings page. The setting takes minutes; the change takes a quarter. Observation tells you what will happen, announcement determines how it is received, and the exception path determines whether the policy is followed or routed around.
What you learned
Section titled “What you learned”- Evaluate mode applies a ruleset without enforcing it and removes the guesswork from rollout
- Where no evaluate mode exists, the audit log tells you how often the restricted action actually occurs
- The observation window must cover a full cycle including periodic processes such as releases
- Sequence from uncontroversial to contentious, one change at a time, with gaps between
- Announce at least two weeks ahead, say what changes and what to do instead, and follow up afterwards
- Prefer targeting over bypass for categorical exceptions; reserve bypass for operational needs
- Time-bound exceptions, and treat a growing bypass list as evidence the rule is wrong
- Roll back rather than debate when a policy blocks real work
- Measure coverage, violations prevented, bypass rate and behaviour change — not whether the setting is on
Exercise
Section titled “Exercise”Use an enterprise or organisation you administer.
-
Pick a rule you would like to enforce. Write it in one sentence, with the reason.
-
Find out how often the behaviour it restricts currently happens, from the audit log or by creating an evaluate-mode ruleset.
-
Predict: how many teams would be affected? Then check.
-
Draft the announcement: what changes, the date, what to do instead, and who to ask.
-
Design the exception path: who grants it, how long it takes, and how long an exception lasts.
-
Identify the periodic process most likely to be affected. Does your observation window cover it?
-
Decide the rollback trigger — what would make you turn it off.
-
Define the outcome metric you would report a quarter later.