gflow: team conventions belong in a config file, not a wiki page

Most engineering teams have conventions: branches are named feature/..., commits follow Conventional Commits, pull requests go to main, two specific people review backend changes, and everything is squash-merged. These rules usually live in a wiki page that new people read once and everyone else remembers approximately.

The result is predictable: half-followed conventions, review requests sent to the wrong people, and commit histories that are hard to read.

gflow is a Go CLI that takes the other approach. The conventions live in a .gflow.yml file committed to the repository, and the tool follows them for you.

One command from changes to a pull request

gflow pr "Add user authentication"

That single command stages the changes, writes a commit message in the team’s format, pushes the branch, and opens a pull request with the right template, base branch, labels and reviewers. It works the same way on GitHub, GitLab and Bitbucket, including self-hosted instances.

The rest of the lifecycle has matching commands: gflow start feature user-auth creates a correctly named branch, gflow sync rebases on the base branch, gflow finish merges with the configured method and cleans up, and gflow release minor bumps the version and creates a release.

The config is the point

branching:
  main: main
  prefixes:
    feature: feature/
    bugfix: bugfix/
pr:
  merge_method: squash
  reviewers: [alice, bob]
  labels: [needs-review]
commit:
  convention: conventional
  require_ticket: false
hooks:
  pre_pr:
    - make lint
    - make test

Because the file is committed, conventions become code:

• They’re reviewed. Changing the merge method or adding a required reviewer is a pull request, with a discussion and a history.
• They’re versioned. You can see when a rule changed and why.
• They’re enforced by default. The easiest way to open a pull request is also the correct way, so nobody has to remember the rules.

Lifecycle hooks follow the same idea. A pre_pr hook that runs make lint and make test means pull requests that fail basic checks are caught on the developer’s machine, before they waste a CI run or a reviewer’s time.

Credentials stay out of the repo

The config names the environment variable that holds the provider token (token_env: GITHUB_TOKEN), never the token itself. The configuration is safe to commit and share, and each developer authenticates with their own credentials.

Why this matters more in 2026

Coding agents create branches, write commits and open pull requests too. An agent can read a wiki page, but it follows a config file and a CLI far more reliably. When conventions are executable, it doesn’t matter whether a pull request was opened by a new hire, a senior engineer or an agent: it comes out the same shape, with the same checks, sent to the same reviewers.

The best conventions are the ones nobody has to remember.