Branch naming rules

[dlorenc]

Overview

There is no server-side enforcement of branch naming conventions. Teams want to enforce patterns like feature/*, fix/*, release/* to keep branch lists organized and enable pattern-based policies.

Design

Config stored in repo (like policies)

Branch naming rules live in .docstore/branch-rules.json on main, versioned like any other file:

{
  "rules": [
    {
      "pattern": "feature/*",
      "description": "Feature branches"
    },
    {
      "pattern": "fix/*",
      "description": "Bug fix branches"
    },
    {
      "pattern": "release/v[0-9]*",
      "description": "Release branches (semver)"
    }
  ],
  "allow_unlisted": false
}

allow_unlisted: false rejects branch names that don't match any pattern.

Enforcement

On POST /repos/{name}/-/branch, the server:

1. Reads .docstore/branch-rules.json from main (cached, same as OPA policies)
2. Validates the requested branch name against patterns (glob matching)
3. Returns 400 with {"error": "branch name does not match any allowed pattern", "patterns": ["feature/*", "fix/*"]} if rejected

CLI

ds branch-rules                           → show current rules
ds branch-rules set --file rules.json     → commit new rules to main

Notes

• main is always exempt from naming rules
• Rules file absence = allow all (no breaking change)
• Patterns use standard glob syntax (* matches any string except /, ** matches including /)