You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Updated the Centralised Repository Governance document to clarify the importance of a governance repository, enhance the narrative around repository drift, and refine the structure and examples for better understanding.
Large organisations often struggle to keep repository settings aligned across many teams. Over time, policies such as branch protection, workflow permissions, and commit signing drift away from the intended standard. A central governance repository that runs automated audits can detect this drift early and give teams clear feedback without interrupting their work.
5
+
It’s easy for repository settings to drift when many teams manage their own projects. A central governance repository, backed by automated nightly audits, helps keep everything aligned with the organisation’s engineering standards while allowing teams to work freely.
6
+
6
7
7
8
## **Problem**
8
9
9
-
When many teams manage their own repositories, settings naturally become inconsistent. Typical issues include:
10
+
As organisations grow, each team naturally sets up repositories in their own way. Over time, these settings begin to diverge:
11
+
12
+
* branch protection disappears or becomes inconsistent,
* and new repositories start life without any safeguards at all.
17
+
18
+
No one notices immediately, and no one does it on purpose. It just... happens.
19
+
Manual audits are slow and rarely complete. Before long, the organisation has dozens of small risks scattered everywhere, hidden in plain sight.
20
+
21
+
## **Story**
10
22
11
-
* missing or weakened branch protection,
12
-
* overly broad workflow permissions,
13
-
* missing or outdated CODEOWNERS files,
14
-
* admin bypass enabled unintentionally,
15
-
* use of risky workflow triggers,
16
-
* or new repositories lacking required protections altogether.
23
+
A platform team in a large engineering organisation realised something worrying: every few weeks, a production incident or security concern could be traced back to a simple repository misconfiguration. Nothing dramatic—just things like a missing review requirement or an overly generous GitHub Actions permission.
17
24
18
-
Manual checking does not scale. Teams focus on delivery, not on remembering organisation-wide rules. As a result, gaps grow slowly and silently, increasing both security exposure and operational risk.
25
+
People weren’t careless; they were busy. They moved fast, created new repos, copied old workflows, and tweaked settings when needed. Over time, these changes compounded into a patchwork of configurations.
26
+
27
+
Instead of telling every team to “be more careful”, the platform team built a small governance repository. It held a clear, versioned baseline of expected repo settings, and each night a GitHub Action scanned every repository, comparing it with the baseline.
28
+
29
+
The next morning, teams received a calm, simple report:
30
+
**Here’s what changed. Here’s where drift happened. Here’s how to fix it.**
31
+
32
+
Within a month, the number of incidents dropped, standards became consistent, and onboarding new repos felt effortless.
33
+
The best part? No one’s workflow was interrupted. The whole system quietly supported good engineering hygiene in the background.
19
34
20
35
## **Context**
21
36
22
-
*The organisation hosts many repositories on GitHub.
23
-
* Teams have autonomy to create and configure their own repos.
*There is no simple way to see where configuration drift has occurred.
26
-
*Automation is accepted and available through GitHub Actions.
37
+
*Many repositories exist across multiple teams.
38
+
* Teams have the freedom to configure their own repos.
39
+
*Engineering or security leadership expects a shared baseline.
40
+
*Visibility across all repos is limited.
41
+
*GitHub Actions or similar tooling is available for automation.
27
42
28
43
## **Forces**
29
44
30
-
***Autonomy vs consistency**— teams should move fast, but common safeguards matter.
31
-
***Scale**— manual audits fail once repo count grows.
32
-
***Transparency**— policies should be visible and reviewable.
33
-
***Low friction**— governance should not slow everyday work.
34
-
***Early detection**— drift needs to be surfaced before it becomes risky.
45
+
***Autonomy vs alignment:**Teams need freedom to build, but consistent safeguards matter.
46
+
***Scale:**Manual reviews fail once repository numbers grow.
47
+
***Transparency:**Policies should be easy to understand and open to contribution.
48
+
***Low friction:**Governance should guide, not block.
49
+
***Early warning:**Small mistakes should surface before they turn into costly incidents.
35
50
36
51
## **Solution**
37
52
38
-
Create a dedicated “Governance Repository” that stores the organisation’s baseline policies as code and contains an audit engine that checks all repositories on a set schedule, such as nightly. The audit compares each repository’s real configuration to the baseline and reports any drift.
53
+
Create a **central governance repository** that stores baseline policies as code and runs a scheduled audit—usually nightly—to compare real repository configurations against the baseline.
39
54
40
-
The governance repository includes three main components:
55
+
The repository contains three essential parts.
41
56
42
57
### **1. Policy-as-Code**
43
58
44
-
Store expected settings in version-controlled files under `policies/`.
45
-
46
-
**Example structure:**
59
+
Store baseline expectations under a `policies/` directory.
60
+
This might include:
47
61
48
62
```
49
63
policies/
@@ -54,157 +68,99 @@ policies/
54
68
tag_protection.yml
55
69
```
56
70
57
-
**Example baseline rule:**
71
+
**Example baseline (branch_protection.yml):**
58
72
59
73
```yaml
60
74
required_pull_request_reviews:
61
75
required_approving_review_count: 1
62
-
enforce_admins: true
63
76
require_signed_commits: true
64
-
dismiss_stale_reviews: true
77
+
enforce_admins: true
65
78
```
66
79
67
-
These files form a clear, shared baseline for all teams.
80
+
These files become the shared, reviewable definition of “how we configure repositories here”.
68
81
69
82
### **2. Audit Engine**
70
83
71
-
A script (written in Python, Node, or Go) loops through all organisation repositories using the GitHub API, retrieves their configuration, and compares it to the baseline.
72
-
73
-
**Python example (simplified):**
74
-
75
-
```python
76
-
from github import Github
77
-
import yaml, os
78
-
79
-
gh = Github(os.environ["GITHUB_TOKEN"])
80
-
org = gh.get_organization("my-org")
84
+
An audit script (Python, Node, or Go) uses the GitHub API to inspect every repository and compare its configuration to the baseline.
0 commit comments