Free lesson · Git Mastery
Repository Governance Overview
Repository Governance Overview
A note from Swati Bajpai, Engineering Manager at Google Search Infrastructure.
What Governance Means for a Git Repository
A Git repository starts simple. One person, one machine, a few commits. The decisions about who can do what are implicit: the only person involved makes them all. As the repository grows - more contributors, more critical role in the organization, more dependencies - governance becomes explicit. Decisions about access, conventions, processes, and lifecycle now require deliberate choices.
Governance, at the repository level, is the set of decisions about who has what authority and how decisions get made. It's structural rather than situational - not "what do we do about this PR?" but "who decides on PRs and how?" The structural decisions shape every situational one.
Module 20 covers governance and collaboration patterns. This topic frames what governance means and the categories of decision. Subsequent topics cover specific governance mechanisms - branch protection (20.2), code owners (20.3), access control (20.4), audit (20.5), multi-repo coordination (20.6), open source workflows (20.7), and long-term maintenance (20.8).
I manage a fourteen-person team at Google Search Infrastructure. The governance patterns my team uses have evolved over years. They're not unique to Google; the patterns are widely applicable to teams operating shared codebases. This topic distills the general framing.
The Categories of Governance Decision
The decisions a team makes about a repository fall into several categories:
Access decisions. Who can read, write, administer the repository? At what level of granularity?
Workflow decisions. What process do changes go through? Required reviews, status checks, signing requirements?
Convention decisions. How are commits formatted, branches named, releases tagged?
Quality decisions. What's required to merge? Tests, security scans, formatting, documentation?
Ownership decisions. Who is responsible for which parts of the code? Who reviews changes to which areas?
Lifecycle decisions. When is the repository archived? Who decides? What's the deprecation process?
Each category contains many specific decisions. Together they form the governance model. A repository with mature governance has explicit, documented answers to each. A repository without it has implicit answers that vary by who you ask.
The discipline of governance is making the answers explicit. The benefit is consistency and predictability for everyone working with the repository.
Why Governance Matters
For a one-person project, governance is unnecessary overhead. For a team project, governance becomes valuable for several reasons:
Predictability. Engineers know what to expect. The same change submitted by different people goes through the same process.
Onboarding. New engineers learn the conventions explicitly rather than absorbing them by osmosis.
Audit and compliance. Many environments require demonstrable processes. Governance makes them demonstrable.
Reduced bus factor. Conventions documented in governance aren't lost when individuals leave.
Cross-team collaboration. Other teams know how to interact with your repository.
Defense against drift. Governance establishes the baseline; drift is visible against it.
The benefits compound. Each individually is modest; together they shape how the team operates over years. Teams with mature governance can absorb personnel changes, scale to larger groups, and operate with confidence in their processes. Teams without it depend on individual memory and ad-hoc decisions.
Levels of Governance Maturity
Teams can be at different governance maturity levels:
Level 1: Informal. Conventions exist but aren't documented. Knowledge is in heads. New engineers learn by trial and error.
Level 2: Documented. Conventions are written down. Engineers can read what's expected. Enforcement is mostly cultural.
Level 3: Enforced. Conventions are enforced via hooks, branch protection, and CI. Deviation is caught automatically.
Level 4: Audited. Compliance is measured. Reports show adherence. Trends are tracked.
Level 5: Continuously improved. Governance is treated as a living system. Regular reviews. Conventions evolve.
Most professional teams operate around levels 2-3. Highly regulated environments require level 4. Few teams reach level 5; those that do typically have governance as part of their culture, not just their process.
The progression takes years. Each level requires investment. The investment compounds - Level 3 enforcement only works on Level 2 documentation; Level 4 audits only work on Level 3 enforcement.
Who Makes Governance Decisions
Governance is meta-decision-making: who decides on the decisions. The patterns I see:
Individual maintainer. One person decides; appropriate for small projects.
Maintainer team. A small group of maintainers decides; common in open source.
Engineering manager. EM owns governance; common in corporate teams.
Team consensus. The whole team decides; works for small teams; gets unwieldy at scale.
Senior engineers. Tech leads or senior engineers; common in larger teams.
Architecture committee. Cross-team body for organization-wide decisions; common at enterprise scale.
The right pattern depends on team size and structure. Small teams can use consensus. Larger teams need clearer decision authority. The discipline is choosing a pattern explicitly rather than letting it emerge implicitly.
For my team, I (as EM) own governance decisions in consultation with senior engineers. The pattern is documented; engineers know how decisions get made.
A Pattern at Google Search Infrastructure
The team's governance documentation includes:
Repository: search-infra
Owners: Search Infrastructure team
EM: swati@example.com
Tech Lead: brandon@example.com
Access tiers:
- Read: Anyone at Google
- Triage: Search org members
- Write: Search Infrastructure team
- Maintain: Tech lead and EM
- Admin: EM only
Decision-making:
- Day-to-day code review: any team member
- Convention changes: tech lead + EM
- Major restructuring: team consensus
- Access changes: EM
- Archival/deletion: EM + director
Conventions:
- Commit messages: Conventional Commits (Topic 18.5)
- Branch naming: feature/*, hotfix/*, release/*
- PR titles: same as commit format
- Required reviewers: 2 for production-touching code
Enforcement:
- Branch protection on main and release/*
- Required CI checks listed in branch protection
- Commit-msg hook enforces format
- Server-side hooks enforce signing for protected branches
The documentation is about 800 words for our team. It captures the decisions explicitly. New engineers can read it and know what to expect. Other teams can read it and know how to interact with our repository.
The documentation lives in the repository itself, as GOVERNANCE.md or similar. It evolves with the repository; changes go through review like any other content.
When Governance Goes Wrong
The patterns that signal governance problems:
Inconsistent decisions across similar cases. Different engineers get different answers; signals lack of clear governance.
Surprise about who has access. Engineers discover access they didn't know about; signals access wasn't tracked.
Convention drift over time. What was followed three years ago isn't followed now; signals lack of enforcement.
Bottlenecks in decision-making. Everything requires one person's attention; signals overcentralization.
Frustration with the process. Engineers see governance as obstacle, not infrastructure; signals process needs adjustment.
Audit findings. External auditors find gaps; signals governance is incomplete.
Each signal prompts investigation. The response isn't always tightening governance - sometimes it's loosening, sometimes restructuring. The discipline is treating these signals as feedback rather than ignoring them.
A Specific Story From My Stripe Days
When I joined Stripe in 2018, I joined a team with documented governance. The documentation was explicit about access, conventions, and decision-making. Engineers knew the rules.
But the documentation was 3 years old at that point. Some rules had evolved organically - engineers followed them but the docs didn't reflect them. Some rules in the docs weren't actually followed anymore. Engineers absorbed the actual rules from peers, not from docs.
The cleanup took about two weeks of part-time work. I went through the docs section by section, comparing to actual practice. Updated where practice had evolved. Removed rules that were no longer followed. Added rules that had emerged but weren't documented.
The cleanup wasn't dramatic. It was just making the docs match reality. After it, new engineers got accurate information from the docs. Existing engineers found nothing surprising. The investment was modest; the ongoing benefit was substantial.
The lesson: governance documentation degrades without attention. The degradation is gradual and invisible until someone notices. Periodic cleanup keeps the docs useful.
Governance as Code
A modern pattern: encoding governance in the repository itself.
search-infra/
├── .github/ # CI and platform integration
│ ├── workflows/ # GitHub Actions
│ ├── CODEOWNERS # Topic 20.3
│ └── branch-protection.yml # IaC for branch protection
├── GOVERNANCE.md # Human-readable governance
├── CODE_OF_CONDUCT.md # Behavioral expectations
├── CONTRIBUTING.md # How to contribute
├── SECURITY.md # Security disclosure process
└── ...
The governance lives with the code. Changes to governance go through review. The history of governance changes is visible in Git. New engineers find everything they need in one place.
This pattern - "governance as code" - applies the same discipline to governance that applies to code. The result is governance that evolves deliberately and visibly.
What Comes Next
Topic 20.2 covers branch protection policies in detail - the technical enforcement of governance. Topic 20.3 covers code owners. Topic 20.4 covers access control. Topic 20.5 covers audit. Topic 20.6 covers multi-repository coordination. Topic 20.7 covers open source workflows. Topic 20.8 closes with long-term maintenance.
What Goes Wrong
Warning: Common governance mistakes:
No documented governance. Knowledge in heads; lost when people leave.
Documented but not enforced. Conventions become aspirational; drift over time.
Too much governance for small teams. Overhead exceeds value.
Too little governance for large teams. Inconsistency and confusion.
No process for changing governance. Becomes calcified; can't adapt.
Governance as separate from code. Treated as bureaucracy rather than infrastructure.
Try It
Exercise: Inventory your governance:
- Find your team's repository. Does it have a GOVERNANCE.md or equivalent?
- Identify three governance decisions that exist in practice but not in documentation.
- Identify three documented rules that aren't actually followed.
- Map your team's governance maturity to a level (1-5).
- Identify the single highest-leverage governance improvement.
- Discuss with your team: what governance changes would help?