Skip to main content
Protected branches restrict who in your org can read or write a specific branch. Use them for production, customer data, or anything where org-wide access is too broad.

​
Creating a protected branch

The --protected flag marks the branch as invite-only, and it only takes effect while you’re creating a branch with -b. Leave it off and capy checkout -b production asks whether to make the new branch protected, defaulting to no.

​
Access model

  • Org-wide branches (the default, e.g., development) - every member of the project can read and write.
  • Protected branches - the branch has its own grant list, stored on the service alongside the branch. A member reaches the branch only once someone grants them access to it.
Grants are a member-level thing. In capy users, owners and admins expand to a single Access to all branches row, and a project admin already reaches every branch in their project, so neither needs a grant. Enforcement lives on the service, not in a separate key: every branch in a project shares one project key, and what stops an ungranted user is that the service won’t hand over the branch. capy checkout production without access gets a 403 and stops:
Capy fetches the branch before it touches local state, so a refusal leaves you on your current branch with your .env intact.

​
Granting access

Two ways to grant a member access to a protected branch. capy users opens the interactive members list. Expand a member with Enter, expand the project they should have branch access on, and that project’s branches appear with the member’s access state next to each one:
Move the cursor onto a branch row that reads no access and press g to grant. It flips to access granted immediately, and pressing g again revokes it. g only does something on a (protected) branch under a project the member holds as member - project admins already reach every branch, so their rows have nothing to toggle.

​
From scripts and CI

Two subcommands wrap the same calls without the TUI - useful in automation:
Both take <email> <project> <branch> and exit non-zero on failure. The interactive TUI dispatches to the same service endpoints, so behavior is identical. The user must already be in the org - a grant doesn’t invite anyone. Neither command prompts for the grant itself, but both authenticate first and fall back to the interactive browser sign-in when your cached session can’t be refreshed, so a CI job needs a session that’s still valid.

​
Typical split

​
What’s next

Branches overview

How branches fit into the sync loop.
Last modified on August 11, 2026