Overview
What Ghostbranch is, the problem it solves, and where to start.
Ghostbranch gives a public GitHub repo private feature branches. You build unreleased work in a private copy of the repo, test it with the same CI, and publish it only through one gated step that a person approves.
The problem
Section titled “The problem”GitHub has no private branches in a public repo, and a fork of a public repo is always public. So teams that need to keep some work private keep a private mirror by hand. They sync it, run CI on it, and copy the work back out when it’s ready.
Every one of those steps is manual. And on the way out, one stray commit message, internal file or secret can leak into the public repo.
How it works
Section titled “How it works”- Work privately. Each feature lives in a private shadow repo that mirrors your public one. Its CI runs there, just as it would on the public repo.
- Sync flows in.
ghostbranch syncbrings publicmaininto the shadow repo. Nothing flows back on its own. - Promote is the only way out. The gate rebases the feature on public
main, runs the full CI, and scans exactly what would go public for leaks. Then a person approves, and Ghostbranch opens an ordinary pull request on the public repo.
Ghostbranch runs on your own machine, as a command-line tool. There’s no Ghostbranch server or hosted service: it talks only to GitHub.
Who it’s for
Section titled “Who it’s for”- Teams on an open-source repo who need to keep some work private until it’s ready: a feature before its launch, or a fix under embargo.
- Coding agents, and the people who run them. Every command has a JSON output for agents. An agent can run the whole loop, while publishing stays with a person.
Where to go next
Section titled “Where to go next”- InstallPut the ghostbranch binary on your machine and check it works.
- Log inGive Ghostbranch a GitHub token, with its app or a token of your own.
- Set up a repoCreate or adopt the private shadow repo with ghostbranch init.
- Your first featureStart, gate and publish a feature, from start to merge.
- Working with a coding agentLet an agent run the loop, and decide what it may publish.
Quick start
Section titled “Quick start”Already installed and logged in? Run these in a clone of your public repo, then read Your first feature for what each one does: