---
title: Edit configs and OpenAPI specs with branches | Stainless docs
description: Safely test OpenAPI and config changes using branches. Preview SDK changes, commit with changelogs, run early access programs, and merge to main when ready.
---

Branches let you iterate and experiment with your Stainless config, OpenAPI spec, and the resulting changes to your SDKs and docs before merging to `main`. You can also use branches to do things like run early access programs.

Use the branches menu in the Studio to find, create, manage, and switch between branches.

![The branches menu in the Stainless studio with the main branch selected, a search field, several other branches listed, and a create a new branch option at the bottom.](/docs/_astro/branches-menu.BKXtKU-u_ZdgFRd.webp)

Custom code is also supported on dev branches. See our [custom code guide](/docs/guides/add-custom-code#project-branches/index.md) for more info.

## Create a branch

There are two ways to create a new branch inside the branches menu:

1. Press the **Create new branch** button, provide a name for your new branch, choose the source branch you want to create it from, and press **Create branch**
2. Type the name of a branch that doesn’t exist into the search field, then select the **Create branch <*your-new-branch*>** option to create a new branch using `main` as the source branch

![The branches menu showing creation of a new branch via the search field.](/docs/_astro/branches-create-new.68ej34eS_Z25YEEp.webp)

When you create a new branch, the Studio will automatically switch to it. The current branch name is always shown in the branches menu button.

## Branch statuses

A branch can have one of three statuses, which are shown in the branches menu for the current branch:

- ● Up to date
- ● Unsaved changes
- ● *X* builds ahead of main

![The branches menu on a documentation-updates branch with a status of '2 builds ahead of main'.](/docs/_astro/branches-statuses.DbtBULi6_2iMtq7.webp)

The branches menu does not indicate when a branch is behind `main`.

## Save changes to a branch

When you have ● Unsaved changes, press the **Save and build branch** button in the top right, or use the `Command` + `S` keyboard shortcut to save them and start a new build.

The Studio doesn’t save changes automatically, but you will be warned if you try to navigate away before saving unsaved changes.

## View, download, and test changes

When you save changes to your branch, a new build will start. When the build completes, you can download your updated SDK using the download button next to the **Build** command in the lower left panel of the Studio. Once downloaded, you can install and test your updated SDK.

![A completed build showing success next to all steps, and a download button next to the build step.](/docs/_astro/build-status.BTFSb-A3_2659vX.webp)

You can also use the other links in the lower left panel to view build logs and code changes on GitHub.

## Collaborate on a branch

To work with others on a branch:

1. Go to the branches menu
2. Press the ⋮ button next to the name of the branch you want to collaborate on
3. Select the **Copy branch URL** option
4. Share the URL with the people you want to collaborate with

The URL will open the Studio to the branch you selected. If you share the link with someone who isn’t logged into Stainless, they’ll need to login or create an account to continue.

## Rebase on or reset to `main`

To rebase on, or reset, the current branch to `main`, select the appropriate option in the branches menu.

The rebase and reset options don’t appear when you’re on `main`, or when you’re on other special branches like the ones used in Stainless preview workflows.

If a rebase results in a merge conflict, you’ll need to clone the config repo and rebase and resolve manually.

## Merge to main

To merge a branch to `main`, press the **Merge to main** button in the top right corner of the Studio. In the dialog that appears, provide a commit message in the [conventional commits format](https://www.conventionalcommits.org/en/v1.0.0/) and, optionally, a commit message description.

Example conventional commit messages

```
# Initial version: 1.2.3


# Minor version bump — 1.3.0
feat(api): add new endpoint to get user details


# Patch version bump — 1.2.4
fix(api): correct parameter name in getUser endpoint
docs(api): clarify usage of currencies


# Breaking change, major version bump — 2.0.0
feat(api)!: remove deprecated endpoint getUser
```

The conventional commits format is required for [automatic version incrementing](/docs/guides/publish/#versioning-and-releases/index.md).

When you merge changes that don’t impact your SDK’s functionality (e.g., you modify a comment in your Stainless config or OpenAPI spec), a placeholder commit message will be used on your SDK’s repository instead of the commit message you provide. This prevents clutter in your SDK’s release notes from non-material changes to your configuration or spec.

When you’re ready, press the **Squash and merge** button to merge your changes. After your branch is merged to main it will automatically be deleted to keep things tidy.

## Delete a branch

To delete a branch, press the ⋮ button next to the name of the current branch and select the **Delete** option.

You can’t delete the `main` branch and some other special branches used for Stainless functions like preview workflows.

## Run an early access program

Branches allow you to create SDK builds with unreleased changes. You can share those builds with users in early access or beta programs to get their feedback before release.

Create a new branch, then make the changes you want your early access users to see. This usually involves updating your OpenAPI spec and may also require adjustments to your Stainless config to do things like add new endpoints, define models, and so on.

Save and build your branch to create new versions of your SDKs with the changes you’ve made.

### Distribute early access SDKs yourself

When your build succeeds, a download button will appear next to the **Build** step in the lower right of the Studio. Press that button to download the updated SDK, then distribute it to your early access users.

### Provide early access users with an install command

After your build succeeds, click on the **Build** step in the lower left of the studio to view the build action logs on GitHub. Expand the **Upload tarball** log and you’ll find an install command you can share with your early access users.

Example install command from upload tarball log

```
Uploaded build to Stainless storage.
Installation: npm install 'https://pkg.stainless.com/s/your-early-access-branch/123...'
```