Feature request (Git storage): defaultBranch option separate from branchPrefix

Summary

We run Keystatic with environment-specific config (local, preview, staging, production, and so on), driven by an environment variable. In our keystatic.config.tsx, something like getStorageByEnvironment reads that value and sets the storage field accordingly.

That works well for swapping repos or modes, but we keep hitting the same wall: every Git-backed environment ends up tied to the repo’s default branch, even when the app we’ve deployed is clearly “on” another line of work. In our case, release and production can be a major version apart. The content and commits we actually want editors to touch on release live under a release/… convention, while production stays on what is usually main for us.

We’re not asking branchPrefix to do double duty. Prefixes are great for how we name or scope working branches (develop/, release/, main/). What we’re missing is a simple, explicit knob for “this environment’s home branch”, the branch Keystatic should treat as the default baseline for that deployment, so release editors aren’t dropped onto the same default branch we use in prod.

What we’d like

A Git storage option (we’ve been calling it defaultBranch in our heads, happy to bikeshed the name) that lets us set that baseline branch per environment, alongside the existing branchPrefix where we already use it.

If the option is omitted, behaviour should stay exactly as it is today (repo default on the host, often main for us in production). That backwards compatibility matters a lot for us.

What our config would look like

Local

{
  kind: "local",
}

Dev

storage: {
  kind: "github",
  repo: "john/doe",
  defaultBranch: "develop",
  branchPrefix: "develop/",
},

Release

storage: {
  kind: "github",
  repo: "john/doe",
  defaultBranch: "release",
  branchPrefix: "release/",
},

Production, we’d leave defaultBranch out on purpose and keep today’s behaviour, while still using our usual prefix:

storage: {
  kind: "github",
  repo: "john/doe",
  branchPrefix: "main/",
},

(Adjust john/doe and branch names to match reality; the point is release gets an explicit home branch, prod doesn’t need the new field.)

Why it matters for us

We deploy one Keystatic instance per environment in CI. Each instance should open and push against the branch line that matches the code we actually shipped, not a one-size-fits-all default. That cuts down on confusing diffs, stale content, and “why am I editing the wrong branch?” moments for less technical editors.

Success criteria (from our side)

• The option is documented with a plain-English description of what it changes (read/write/UI, whatever the product does today, just spelled out).
• Omitting it keeps current behaviour unchanged.

Related

• #952 – More settings for github mode looks closely related (default branch vs prefix, safer workflows, etc.). If the maintainers prefer a single thread, we’re happy to paste this there as a comment instead of splitting the conversation.

Contribution

If the API shape makes sense to you, we’re willing to open a PR to implement it.

Begin with the keystatic.config.tsx examples and trace the GitHub storage configuration and existing branchPrefix handling. Verify how the repository default is currently used for the baseline, reads, writes, and UI, then document and test that an explicit defaultBranch changes the environment's home branch while omission preserves current behavior.