Tools & processes · 2 min read
Working in GitHub
Where the work actually lives: the code, the handbook, and most of the decisions, in repos, in the open. Here's how we use them.
Most companies scatter their work across a chat app, a wiki, a task tracker, a docs tool, and six people's memories. We try to keep it in one place: a repo, in the open. For the company, that place is the Flagon GitHub org: the flagon repo, which is this site and the handbook, lives there, and so do most of the decisions that shape the company. Flagon is also an organization on our own forge, at g1t.sh/flagon-io, which is where g1t itself lives. Each product picks where its own repo lives as part of owning its stack. The habits below are the same wherever the repo is. If it matters and it's writeable, it probably belongs in a repo, in the open. This is the mechanical side of how this handbook works and defaulting to open.
Why one place
When the work lives in one system, a new person can reconstruct how the company got here by reading, rather than by asking around and hoping someone remembers. Issues hold the discussion, pull requests hold the change and the reasoning, and the history holds the "why." A decision made in a disappearing chat message is one the company will have to make again in six months; a decision made in a pull request is one anyone can find later.
How we use it
- Issues are for thinking out loud. A problem, a proposal, a rough idea: open an issue, describe it, and let people poke at it in public. Half-formed and visible beats polished and private.
- Pull requests are how things change, whether the thing is code or a handbook page. You make the edit, explain why in the description, and it gets reviewed and discussed before it merges. The reasoning lives next to the change.
- Write the "why" down, in the PR description, the commit, the issue. The diff shows what changed; you're on the hook for why. Future readers, including future you, need the reasoning more than the mechanics.
- Public by default. Work happens in public repos unless there's a specific reason it can't (see what we keep private). Closing something should have to justify itself; opening it shouldn't.
New to working this way?
If a code host has mostly been a code thing for you, using one to run a company can feel odd at first, and that's fine. You don't need to be a git wizard. The core loop is small: open an issue to raise something, open a pull request to change something, and say why in plain words. Ask in Discord if you get stuck; someone will happily walk you through it.
A decision that lives only in someone's head is a decision the company doesn't really have yet. Writing it into an issue or a PR is how a small crew keeps working after the person who knew is off that day, or gone.