Build branches

A branch is a named line of builds in one app, such as main, staging, or feature-login. Every build belongs to one branch and never moves to another. Test runs, sessions, and Atlas evidence record the branch of the build they used.

Each app has its own branches, and its first upload sets its default branch. Use separate apps for builds that differ in platform or configuration, such as bundle ID or backend environment, and branches for lines of work on the same app.

What branches are forCopy Anchor Link

• Keep a source-of-truth branch current. Upload each new main or staging build to that branch and test or explore it, from CI or a cloud AI agent automation, so its results and Atlas map follow the app you ship. See Keep a source-of-truth branch current.
• Keep feature work apart. Builds you upload from a feature branch go to a branch of the same name, so runs and links on main keep using main's builds.
• Test a chosen branch once, or save it so every run uses it. See Test a branch.
• Compare main with a feature branch in Atlas, or by running the same workflow on both. See Compare two branches.
• Hold a steady release candidate. Pin staging to one build. See Pin a release candidate.

Default branch and default buildCopy Anchor Link

The app's default branch is the branch a run uses when nothing else picks one. A new app's default branch is the branch of its first upload, such as main; until its first upload it's base. Pull request preview builds from the Revyl GitHub and GitLab apps don't set it. Change it with revyl app branch default main --app "My App" or Make default branch… in App settings > Build branches. Changing it doesn't change saved choices that name a branch.

Each branch has a default build, the build a run on the branch uses when it doesn't pick one:

A usable build isn't deleted and is the kind the app runs: a simulator .app for iOS or an .apk for Android. Uploads still in progress don't count.

On an app's Builds page, the Default tag marks each branch's default build. In branch lists, Default with a house icon marks the app's default branch.

Git branch detectionCopy Anchor Link

Without --branch, uploads go to your Git branch, and runs try it first. The CLI, the terminal UI, the Revyl GitHub Actions (upload-build, run-test, run-workflow), and MCP read the Git branch of the code they run from:

What happens with the detected branch:

• Uploads go to the Git branch and create it if it doesn't exist. A Git branch name that can't be a Revyl branch fails with Detected Git branch is not a valid Revyl branch; use --branch <name>.
• Runs, sessions, and explorations use the Git branch when it has a usable build. Otherwise they use the app's default branch and say so, with a notice such as Git branch "feature-login" has no usable build; using the app's default branch "main". A workflow decides this for each app. If the default branch has no usable build either, the run fails and names both branches.

Build lists, Atlas, the MCP build list, and the terminal UI's build browser show All branches until you pick one.

How a run picks its buildCopy Anchor Link

A run uses the first of these that applies:

1. A choice for this run, such as --branch staging, --build-id, --all-branches, or a branch or build picked in a run dialog. See Run options.
2. The saved choice of the test, workflow, or embed, unless it's Default branch.
3. Your Git branch, when it has a usable build. See Git branch detection.
4. The app's default branch.

A choice has a branch part and a build part. In the dashboard, both live in one Build field.

Once a run starts, its branch and build stay fixed, including retries.

New saved choicesCopy Anchor Link

• Tests created in the dashboard, and workflow app overrides when you choose an app, start on All branches · Latest build, the newest build on any branch, so a pull request job can run another pull request's upload. To test the pull request's own build, pass the upload's build ID to the run, or save it on Default branch so it runs on the pull request's own branch.
• Tests saved from a session, tests created with the CLI, YAML, MCP, or the API, and embeds start on Default branch with Automatic.

Pull request buildsCopy Anchor Link

Pull request jobs on GitHub Actions and Buildkite upload to the pull request's source branch. The Revyl GitHub and GitLab apps upload their preview builds there too, as ordinary builds that can become that branch's Latest build. The apps skip pull requests from forks. If a source branch name can't be a Revyl branch, the app's Revyl configuration check fails and no preview is built.

Every source branch you upload from becomes a Revyl branch. To choose between per-PR branches and one shared branch, see Choose where CI uploads go.

Common tasksCopy Anchor Link

Keep a source-of-truth branch currentCopy Anchor Link

Choose the branch you want to stay current, usually main or staging, and keep feeding it new builds.

revyl build upload --file ./build/app.apk --app "$APP_ID" \
  --branch main --yes --json > build.json
BUILD_ID=$(jq -er '.build.build_id' build.json)

revyl workflow run smoke-tests --android-app "$APP_ID" --android-build-id "$BUILD_ID"
revyl explore run "$APP_ID" --build-id "$BUILD_ID"

Make it the app's default branch. Choices saved on Default branch then use it in dashboard runs, and in runs from your code when your Git branch has no usable build:

revyl app branch default main --app "My App"

Test a branchCopy Anchor Link

Run once on a branch without changing saved settings:

revyl test run login --branch staging
revyl workflow run smoke --branch staging

A workflow's --branch applies to every app it runs; it fails if one of them doesn't have that branch or has no usable build there. In the dashboard, use Run on a branch… on a workflow or a selection of tests: type a branch name or choose All branches, then Automatic or Latest build. On one test, use Run with a build… (Run async with a build… in the editor).

To make every run use a branch, save it:

revyl test build set login --branch staging
revyl workflow app set smoke --ios <ios-app-id> --ios-branch staging

In the dashboard, set the Build field in the test's settings, or turn on App Override in the workflow's Settings tab and set iOS build or Android build. For every option, see Run options and Saved test and workflow choices.

Pin a release candidateCopy Anchor Link

Pin staging to one build so runs on it keep that build while newer builds arrive:

revyl build list --app "My App" --branch staging
revyl app branch pin staging <build-id> --app "My App"

Runs that choose Latest build still use the branch's newest build. Unpin with revyl app branch unpin staging --app "My App".

Compare two branchesCopy Anchor Link

• Atlas. Pick a branch in Atlas's scope control, or open each map with revyl atlas open --app "My App" --branch <name>; links keep the branch, so you can open two side by side. revyl atlas brief and revyl atlas graph take --branch too. Branches filter evidence, not screens: merging or hiding screens applies to the whole app.
• Test results. Run the same workflow with --branch main and --branch feature-login and compare the reports. A test's history page can be filtered by branch; workflow history shows each run's build and branch.

Check which build a run usesCopy Anchor Link

revyl build which shows the branch and build a run on the app would use, and why, without starting one:

revyl build which --app "My App"
revyl build which --app "My App" --branch staging
revyl build which --app "My App" --json

It uses --branch, otherwise your Git branch when it has a usable build, otherwise the app's default branch, then that branch's default build. It prints the app, branch, reason, build, and default build, and prints the fallback notice on stderr when your Git branch couldn't be used.

• It reads the app's selection, not a test's or workflow's saved choice.
• HEAD here is a literal branch name.
• A failed selection exits nonzero without a result.

Manage branchesCopy Anchor Link

Each row in Build branches also offers View builds and Open in Atlas.

Uploads also create branches: an upload to a branch name or Git branch that doesn't exist yet, or a new name typed in the dashboard's upload sheet. Creating a branch that exists returns it. A pin must be a build on that branch. MCP tools can't rename or pin branches or set the default branch.

Branch names are case-sensitive, unique within the app, 1 to 255 characters, with no leading or trailing spaces and no control characters. A rename keeps the branch's ID, so saved choices follow it; scripts that pass the old name need the new one, and an upload from a Git branch with the old name creates a new branch. Branches can't be deleted or archived. Lists show the default branch first, then the rest by latest activity: creating a branch, a new build, a rename, or a pin change moves it up.

From the CLI:

revyl app branch list --app "My App" --page 2 --page-size 100 --json

• list marks the default branch (default) and shows 50 branches per page (--page-size up to 100). Its columns are BRANCH, BRANCH ID, DEFAULT BUILD, and BUILD ID.
• DEFAULT BUILD reads Latest build (v4), Latest build (no builds), Pinned build (v1.2), or Pinned build (v1.2, unavailable). BUILD ID is the build a run on the branch uses now, or - when there is none.
• pin takes the ID of a build on that branch, not a version label. List IDs with revyl build list --app "My App" --branch staging.
• The other commands print the branch as Branch: <name> (<id>), or JSON with --json.

CLI referenceCopy Anchor Link

The branch and build options, output, and JSON fields of each CLI command.

Upload and list buildsCopy Anchor Link

revyl build --profile preview --platform ios --branch staging
revyl build upload --file ./app.apk --app "My App" --branch staging --pin
revyl build list --app "My App"
revyl build list --app "My App" --branch staging --page 2 --page-size 50
revyl build list --app "My App" --branch HEAD

• --branch chooses the upload's branch and creates it if it doesn't exist. Without it, the upload goes to your Git branch, created if needed, or the app's default branch when none is detected. When --repo and --commit name a different repository or commit than the checkout, the checkout doesn't choose the branch. Pass --branch when the artifact wasn't built from this checkout.
• revyl init chooses its uploads' branch the same way, so the first build it uploads to an app it created sets that app's default branch.
• --pin pins the branch to the new build. If the version label already exists, the upload reuses that build and doesn't pin; the warning prints the revyl app branch pin command to run.
• Version labels are unique within an app among builds that aren't deleted. A label used on another branch fails with This version already belongs to another branch; use a unique version.
• The output prints App:, Build Version:, Build ID:, and Branch: with what a run on the branch uses now: staging (Latest build: runs use this upload), staging (Latest build: runs use v4), staging (pinned to v1.2; runs that don't choose a build keep using v1.2), or staging (pinned to this build). Keep the build ID to run that exact build later; a remote build job ID isn't a build ID.

build list shows every branch of the app. --branch <name> narrows it to one branch. When no Revyl branch has that name, it lists builds built from a Git branch of that name instead. --branch HEAD means your checked-out Git branch and fails outside Git or on a detached checkout, as in pull request CI. The heading says which filter matched: Builds (Revyl branch: main): or Builds (Git branch: main):. Tables show GIT BRANCH, the branch the build was built from, and across branches REVYL BRANCH, the dashboard's Branch column.

Run optionsCopy Anchor Link

These apply to one run and don't change saved settings:

revyl test run login --branch staging
revyl test run login --branch staging --build-selection latest
revyl test run login --build-id <build-id>
revyl test run login --all-branches
revyl workflow run smoke --branch staging
revyl workflow run smoke --ios-app <app-id> --ios-build-id <build-id>
revyl explore run "My App" --branch staging
revyl device start --app-id <app-id> --branch staging
revyl device install --app-id <app-id> --all-branches

• A workflow's --branch and --build-selection apply to every app it runs. Each app needs that branch and, unless you give it an exact build, a usable build there; otherwise the workflow doesn't start and the error names the apps. Without them, each app falls back from your Git branch on its own.
• With test or workflow --build, the new build uploads to --branch, or your Git branch, and the run uses that exact build. Don't combine --build with --build-selection.
• --ios-app and --android-app replace the workflow's saved app for one run; platforms you don't override use each test's saved choice.
• Output names the branch of each build, such as Build: v1.4 from branch feature-login.
• revyl device history --app-id <id> --branch staging lists sessions that started with a build from that branch.
• revyl dev keeps one branch for startup and every rebuild, and doesn't take --all-branches. See Dev Loop for how it picks the branch and build.

Saved test and workflow choicesCopy Anchor Link

revyl test build show login
revyl test build set login --branch staging --build-selection latest
revyl test build set login --build-id <build-id>
revyl test build set login --all-branches
revyl test build set login --build-selection inherit
revyl test build clear login
revyl test create login --from-file ./login.yaml --branch staging
revyl workflow app set smoke --ios <app-id> --ios-branch staging --ios-build-selection inherit
revyl workflow app set smoke --ios-automatic
revyl workflow app set smoke --ios-all-branches
revyl workflow app show smoke
revyl workflow app disable smoke
revyl workflow app enable smoke
revyl workflow app clear smoke

• test build show prints the saved Branch (Default branch, All branches, or staging (<branch-id>)) and Build (Automatic, Latest build, or Exact build v1.4 (<build-id>)); --json gives the saved IDs.
• test build set saves a branch and build. --build-selection alone keeps the saved branch, so on a test saved on All branches it saves Default branch. To move a test saved on a named branch back to Default branch, choose Default branch in its dashboard settings, or push YAML with build_selection: inherit and no branch_id.
• test build clear resets a test to All branches · Latest build.
• test create takes the same --branch, --build-selection, --build-id, and --all-branches, also with --from-file or --from-session. Without them or a choice in the YAML, a new test starts on Default branch.
• Workflows save iOS and Android separately with the --ios-* and --android-* flags. --ios-automatic saves Default branch with Automatic for iOS, and --ios-all-branches saves All branches · Latest build.
• workflow app show names each app and branch with its ID. disable turns the app override off and keeps its choices, enable turns it back on, and clear removes the choices, like turning the override off in the dashboard.

Terminal UICopy Anchor Link

• The app build browser opens on All branches, including when you return to it. Its branch filter narrows the list and never chooses an upload's destination or a run's build.
• Run, session, and upload pickers start with your Git branch when one is detected: Git branch (feature-login) · falls back to base for runs and sessions, or Git branch (feature-login) for uploads, which create it. Pickers that save a choice, and pickers with no Git branch, start with Default branch (base) and its default build. The other branches follow, most recently active first, with the app's default marked (default).
• Pickers for runs, sessions, and saved choices list All branches · Latest build after the first row. Upload pickers and the build browser don't.
• After a branch, run, session, and saved pickers offer Automatic, Latest build, or Exact build. A workflow run takes a branch name and offers Automatic or Latest build; with no name, it offers Keep saved settings or All branches · Latest build.
• Lists load one page at a time: m loads more, / searches, R retries a failed page, and n names a new branch in an upload picker.

JSON fieldsCopy Anchor Link

• Uploads and builds: branch_id and branch_name, with the build ID at .build.build_id for build upload --file and .version_id for build upload --url.
• Runs (test run, workflow run, workflow status, workflow report, explore run, device start, device install): branch_name for each build, branch_source for where that branch came from, and git_branch_name:
  • branch_source is git_branch (your Git branch), explicit_branch (--branch, or the branch saved on the test or workflow), or default_branch (the app's default branch). It's left out when an exact build or All branches · Latest build chose the build.
  • git_branch_name is the Git branch the run sent, present only when the run consulted it: with git_branch, and with default_branch when your Git branch couldn't be used (it doesn't exist, has no usable build, or isn't a valid Revyl branch name). It's left out for explicit_branch, an exact build, All branches · Latest build, and a run with no Git branch. For example, a fallback reports {"branch_name": "base", "branch_source": "default_branch", "git_branch_name": "feature-login"}.
• build which: app_id, app_name, branch_id, branch_name, branch_source (explicit_branch, git_branch, or default_branch, which a fallback also reports), git_branch_name (as for runs: present with git_branch, and with default_branch after a fallback), build_id, build_version, and branch_build_selection (latest or pinned: the branch's default build).
• build list: versions, count, total, page, page_size, and has_next; with --branch, also branch_filter and branch_filter_kind (revyl_branch or git_branch).
• app branch list: branches, each with is_default, pinned_build_id, pinned_build_version, pinned_build_available, and latest_build (absent when the branch has no builds), plus total, page, page_size, and total_pages.

Deprecated flagsCopy Anchor Link

--set-current on revyl build and revyl build upload pins like --pin. --set-current=false and --no-set-current do nothing. Each prints a warning on stderr, --json output is unchanged, and none appears in --help.

RelatedCopy Anchor Link

• CI Builds: where CI uploads go
• Dev Loop: how revyl dev picks and keeps its branch
• MCP tool reference: branch and build inputs
• YAML test format: a test's saved build fields
• Atlas from the CLI: branch scope for reads