Handbook-as-Code
Treat how the company operates as a versioned repo anyone can submit a merge request against
- Difficulty
- Advanced
- Time to result
- ~months to results
- Steps
- 5
- Confidence
- 93%
GitLab's handbook is the single source of truth for how the company operates — mission, strategy, onboarding, product development lifecycle, even accounts payable — and it is edited the way code is: open a merge request, get it reviewed, merge. New hires are expected to file merge requests against it during onboarding. Larger changes route through defined approvers, and the whole thing is source-available so other companies can fork it.
Origin
GitLab's own practice, described by CPO David DeSanto. It is a deliberate application of GitLab's product (issues and merge requests) to the company itself — internal 'dogfooding' extended to policy.
Core principles
- 01If a decision was made, it goes in the handbook — no internal email, no lost Slack thread.
- 02Anyone can propose a change; the size of the change determines who must approve it.
- 03Handbook change precedes process change — you update the doc, then operate that way.
- 04Guidance, not direction: leaders set the outcome and priorities; teams write their own mini-handbooks for how they get there.
- 05Publishing it source-available means other companies fork it, which is a recruiting and goodwill asset, not a leak.
How to run it
- 1
Declare the handbook the single source of truth
Establish that how the company operates lives in one place. Internally, GitLab is deliberately anti-email: communication happens on an issue, in Slack, or in the handbook. Any durable decision goes into the handbook.
Pro tip The rule DeSanto gives: if two people go back and forth and conclude something important, they update the handbook page or add a new one so everyone benefits.
- 2
Make editing it part of onboarding
New hires are encouraged to open merge requests against the handbook when they hit anything unclear or inefficient. GitLab PMs joke that in their first three weeks the handbook becomes their product — typo fixes, clearer sentences, missing steps.
Pro tip This doubles as a live test of whether a new hire can write clearly and work in the open.
- 3
Define approval tiers by blast radius
Small fixes merge freely. Structural changes have named approvers: introducing a new product category requires the CPO's sign-off; changing the product development framework itself requires the CPO, the CTO and their direct reports.
Pro tip Publishing who must approve what is itself a handbook page — it removes the guesswork about escalation.
Watch out Without approval tiers, a fully open handbook becomes either a free-for-all or a bottleneck through one leader.
- 4
Encode the operating cadence, not just the values
The most useful pages are the operational ones: the product development lifecycle, what is expected of you three weeks before a milestone versus two weeks before, the levelling ladders for PMs. This lets counterparts know when to expect something from you and when not to.
Pro tip Publishing PM competency ladders publicly is one of the most-copied pages — it solves a problem nearly every PM org has.
- 5
Let teams fork it internally
Encourage groups to create their own mini-versions of frameworks that reference back to the master handbook. Whether one milestone is 100% new features and the next is 100% bug fixes is the team's call, as long as the agreed outcome lands.
Watch out Mini-versions must reference the master, not silently diverge from it.
In the wild
A company wanting to redo its UX mission and departmental operating model cloned the UX section of handbook.gitlab.com and used it as their baseline instead of building from scratch.
→ They built their UX function on GitLab's baseline and subsequently became a GitLab customer. DeSanto notes startups have cloned the entire handbook as their starting operating system.
DeSanto sets a three-year and seven-year strategy (GitLab publishes plans out to a 30-year mission) plus the priorities that matter to the company, but explicitly refuses to dictate how each group gets there. Groups own their own prioritization mix per milestone.
→ Responsibility is driven to the lowest level of the org (section → stage → group), which DeSanto credits for GitLab's sustained shipping velocity: 12 releases a year for over a decade, 149 consecutive monthly releases.
Common mistakes
Documenting values but not the cadence
A handbook of mission and values is a poster. The load-bearing content is the operational specifics — what's due when, who approves what, how you get levelled — because that's what lets asynchronous counterparts coordinate without meetings.
Letting decisions die in email or DMs
If a decision lives in a thread, everyone who wasn't on it has to be re-briefed forever. GitLab's anti-email posture exists to force the decision into a durable, searchable, forkable artifact.
Is it for you?
Best for
Distributed or fast-growing companies where the same 'how do we do X?' questions keep getting asked in Slack and the answer depends on who happens to reply.
Not ideal for
Very small co-located teams where the overhead of writing exceeds the cost of just asking the person next to you.
From the transcript
“if you're finding something that's inefficient in a workflow or you're finding something is unclear you're encouraged even as part of your onboarding to open…”
“internally it's on an issue it's in slack or it goes into the handbook”
“if you're going to introduce a new category which is new part of the product it requires my sign off to do that”
“I want to provide guidance I don't want to give you Direction”
From the episode
The GitLab way: Kindness, transparency, and short toes
David DeSanto (CPO)