Try it

Try Ghostbranch in about 5–10 minutes on a throwaway copy of a template repo, from install to a passing gate, then clean up.

The quickest way to see Ghostbranch work is on a repo you don’t mind throwing away. The template ghostbranch-labs/try-ghostbranch has one file, hello.txt, and a CI check that runs on pull requests. A first run takes about 5–10 minutes, most of it logging in and waiting for CI.

1. Make your copy

Open the template and click Use this template → Create a new repository. GitHub makes a full copy of it in your own account, so there’s nothing to download. Keep it public, and name it try-ghostbranch.

With the GitHub CLI, one command makes the copy and clones it, so you can skip the git clone below:

gh repo create try-ghostbranch --template ghostbranch-labs/try-ghostbranch --public --clone

2. Install and set up

Install Ghostbranch with one of these (or see Install for every route):

brew install ghostbranch-labs/tap/ghostbranch     # macOS, Linux
npm install -g ghostbranch                        # anywhere with Node

scoop bucket add ghostbranch https://github.com/ghostbranch-labs/scoop-bucket
scoop install ghostbranch                         # Windows

Then clone your copy (replace <you> with your GitHub username) and run init in it. If you used gh repo create … --clone, you’re already in the copy: just cd try-ghostbranch and run ghostbranch init.

git clone https://github.com/<you>/try-ghostbranch
cd try-ghostbranch
ghostbranch init

Press Enter at each question:

The login. If you aren’t logged in, init shows a short code and opens GitHub’s device page: enter the code and approve. If you’re logged in to the GitHub CLI, it first asks whether to use that login or the Ghostbranch app; Enter picks the app.
The app. When init asks you to install the Ghostbranch app, choose Only select repositories and pick only your copy. GitHub’s page then lists write access to contents, pull requests, workflows, Actions and administration; administration is only so init can create the shadow repo. What each permission is for.

init then creates the private repo <you>/try-ghostbranch-shadow and installs the push guard. It never writes to your public copy.

3. Make a private change

ghostbranch feature start feat/try-ghostbranch
echo "And hello from a private branch." >> hello.txt
git commit -am "Say hello privately"
git push shadow feat/try-ghostbranch

The feat/try-ghostbranch branch is in the shadow repo only. Your public copy on GitHub doesn’t have it.

4. Gate it

ghostbranch gate feat/try-ghostbranch

The gate rebases the change on public main, scans it for leaks, and runs the CI on a draft pull request in the shadow repo. Here it takes about a minute. A pass ends like this:

✓ CI passed                                            1m20s
Gate for feat/try-ghostbranch: checks passed, leak scan clean.
  1 commit(s), scanned as preserve
  candidate fa2ad118513a on shadow PR #1

5. Publish it (optional)

ghostbranch promote feat/try-ghostbranch

It shows what it would publish and asks you to type a one-time code it prints, so only a person at the terminal can publish. Then it opens a normal pull request on your public copy. Merge it there, then run ghostbranch sync.

This is the same publish as promote --plan followed by apply <plan-id> in Your first feature, done in one step.

Clean up

ghostbranch remove
ghostbranch guard uninstall

Then delete <you>/try-ghostbranch-shadow and your copy on GitHub, in each repo’s Settings under Danger Zone. Ghostbranch never deletes a repo itself.

Ready for your own repo? Go to Set up a repo.