Skip to main content
A feature branch is a separate code workstream inside one project. Each tracked branch has its own project-agent chat and sandbox preview, so you can develop and test in parallel without mixing conversations.
Feature branches are currently enabled for selected organizations. If the branch New action is missing from the project branch list, your organization does not currently have access.

​
When to use branches

Use a feature branch when you want a parallel workstream inside the same app:
  • Building a feature while other work continues on the default branch
  • Trying a risky experiment without blocking the main agent
  • Isolating a bug fix while another agent keeps shipping elsewhere
This is still one project — not a separate app, Surface, Module, or conversation fork.

​
What branches isolate (and what they don’t)

Branches isolate:
  • Code — each branch has its own GitHub branch and commits
  • Chat / agent work — each tracked branch has its own project-agent conversation
  • Sandbox runtime — each branch has its own builder sandbox and preview
They do not isolate the project’s development data store. All project branches share the same sandbox data. Schema and data writes made on one branch can be visible to the others.
Coordinate schema and data-changing work across branches. Avoid competing migrations on multiple branches at the same time — one branch’s data changes can affect every other branch’s sandbox preview.

​
Working with branches

Project branch menu with Create new branch and Track existing branch actions
  1. Open the project Branches list or branch selector.
  2. Create or track a branch:
    • New → Create new branch creates a GitHub branch from the currently open branch and starts tracking it in the project.
    • New → Track existing branch makes an existing GitHub branch available in the project builder.
  3. Switch branches from the list. Each tracked branch opens with its own project-agent chat and sandbox.
  4. Work with the agent and test in the builder sandbox preview on that branch.

​
Agent-driven merge

The primary merge flow is agent-driven. From a non-default branch:
  1. Click Merge.
  2. Review the plain-language merge preview and any conflict warning, then confirm.
  3. The request opens in the default branch’s chat. That branch’s agent performs the merge, resolves file conflicts, and verifies the result.
If the default-branch agent is busy, the merge is not queued — wait until its current run finishes, then try again. If the default branch chat has never been opened, open it once first, then retry the merge.
After a successful merge, Stop Tracking the feature branch is optional cleanup.

​
Preview deployments and publishing

Feature branches can create shareable preview deployments for review outside the project builder.
  • The default branch preview uses https://app-slug-preview.stardeck.site.
  • A feature branch preview uses https://app-slug-preview-branch-name.stardeck.site. Stardeck normalizes the branch name so the hostname stays DNS-safe.
  • A project can have up to 5 active feature-branch previews. The default branch preview does not count toward this limit.
Production publishing remains default-branch only. To ship feature-branch work to production, merge it into the default branch, verify the result, then publish. See Publishing & Deployment.

​
Default-branch-only operations

Some project operations stay on the default branch: Work on those from the default branch after merging related changes.

​
Branch management

Open branch settings (gear icon) for a tracked branch to:
  • View on GitHub — open the branch on GitHub
  • Stop Tracking — remove it from Stardeck; any active preview deployment and its hostname are cleaned up, while the GitHub branch stays intact
The default branch cannot be untracked.

​
Feature branches vs conversation forks

Need a scratch pad for plans without changing code? Use conversation forking. Need a parallel agent that can edit and test? Use a feature branch.