Skip to main content

Work with Branches

While developing your API with TakeShape, you will probably want to try out changes before making them live for all of your end users. We make it easy to develop new functionality in isolation with branches.

Every project starts with a default branch named “production”. Every new branch you create will start as a copy of your “production” branch. Every branch has a dedicated URL for its unique GraphQL API and schema. This makes it easy to use TakeShape’s branches during development.

A typical workflow may involve creating a branch in the web client to make your API changes, then moving to the command line to develop against your branch’s unique API endpoint, and finally merging your changes as part of your regular PR or CI workflow.

In the web client​

While in a TakeShape project, you can find the branch menu next to the project name. The branch menu will display the branch you’re currently viewing.

Your ability to use branches is limited by your role in a project:

  • Admins can view, switch to, create, or delete any branch.
  • Editors can view or switch to any branch.
  • Viewers can view only the production branch.

Switch branches​

After opening the menu, you’ll see a list of all the branches in your project. If teammates or collaborators create their own branches, you’ll see them in this list, too.

Click on any branch to switch to it. If you have undeployed changes to your schema, you’ll be prompted to resolve those changes before switching.

Find or create branches​

To find a specific branch by name, start by typing in the menu’s search field. It will reveal any branches matching what you type, as well as the option to create a new branch with the name you’ve typed in.

If you create a branch with the name you’ve typed in, you will be automatically switched to it. If you have undeployed changes to your schema, you’ll be propmted to resolve those changes before creating the branch.

Delete branches​

To delete any existing branch, select the “Delete” icon next to the branch’s name in the list. You cannot delete the branch you’re currently on, nor can you delete the default “production” branch.

Promote branches​

When a branch that is not your "production" branch is active, you'll have the option to promote that branch.

Promoting a branch will copy its contents into your "production" branch and then delete it. You'll be automatically switched to your "production" branch.


Be careful with this operation. It will immediately impact your project's production GraphQL API. This could lead to errors in any applications that consume it.