Base Build Tutorial for Git

Learn how to configure the correct base builds to compare against

When you push changes to your codebase and have Percy generate screenshots, Percy groups the screenshots in snapshots, and snapshots into a build. New screenshots are compared to baseline screenshots from a previous build. This previous build is also known as the base build.

Percy takes a lot of care in automatically selecting the best base build to give you clean, accurate diffs. This page documents how Percy determines what build to use as the base build when generating comparisons.

Introducing workflows

Linear or QA workflow: When you are using SCM (Github, Gitlab, Bitbucket etc) for your software development but functional or visual testing is done in a single branch (linear). For example, generally QA team perform regression testing in a QA or Pre-prod environment without testing individual feature branches on which developers work on developing that feature.

Non Linear or Developer workflow: When you are using SCM (Github, Gitlab, Bitbucket etc) for your software development and functional or visual testing is done in every feature branch before it’s merged to master or main branch. For example, Dev team or QA automation team has setup test automation to run on every PR & on success only merge will be allowed.

Hybrid workflow: When you are using SCM (Github, Gitlab, Bitbucket etc) for your software development and functional or visual testing is done in every feature branch before it’s merged to master or main branch and also regression testing is performed in a pre production environment before release is done. For example, Dev team or QA automation team has setup test automation to run on every PR & on success only merge will be allowed. Further regression testing in done on pre production branch before actual production deployment.

How base build selection works?

Please read our base build selection document for conceptual understadning, explaining how base build selection is done under different branching strategies. Read more about Base build selection.

Let’s study Percy base build selection under 3 project settings:
Percy project settings:

• Default base branch
• Auto-approved Branches
• Approval required branches

Also 2 ways of creating Percy builds:

• PR or Pull request builds
• No PR or Feature branch builds

Where can you see those projects settings?

You can see all three branch related settings in you Project Settings page.

What are the default values for the above settings?

• Default base branch - master (can’t be blank)
• Auto Approved Branches - master (can be blank)
• Approval required branches - empty (can be blank)

Quick reference images to these settings:

When Approval Required branch is set

How to find right branching strategy?

• Check your current testing setup being used during visual testing
  • Do you want Percy to auto select base build?
  • Do you want to mark a build manually to be selected as base build?

Let’s try to understand base build selection with examples:

Linear or QA workflow (Single branch)

Base build selection case 1: Auto selection of previous build as base build & auto approve

Percy project settings (Default):

• Default base branch - master
• Auto-approve Branches - master
• Approval required branches - none (empty)
• NO PR

User Narrative: I am creating all the builds in Percy without PR from a single branch, which is master and keeping my project settings as default.

Which build is base build for b3?

• Build b2

Reason: As Percy perform comparison against previous build not previous approved build by default until appropriate Approval required branch is set.

Base build selection case 2: Auto selection of previous build as base build but no auto approval

Percy project settings:

• Default base branch - master
• Auto-approve Branches - none (empty)
• Approval required branches - none (empty)
• NO PR

User Narrative: I am creating all the builds in Percy without PR from a single branch, which is master but turning off auto approval by removing master branch from auto-approval branches.

Which build is base build for b3?

• Build b2

Reason: As Percy perform comparison against previous build not previous approved build by default until appropriate Approval required branch is set.

Base build selection case 3: Only select latest approved build as base build from QA branch & no auto approval

Percy project settings:

• Default base branch - QA
• Auto-approve Branches - none (empty)
• Approval required branches - QA
• NO PR

User Narrative: I am creating all the builds in Percy without PR from a single branch, which is QA & turning off auto approval by removing QA branch from auto-approval branches, also turning on approval required in this QA branch by setting value under approval required branches.

Which build is base build for b3?

• Build b1

Reason: As Percy perform comparison against previous approved build not previous build due to Approval required branch is set to QA

Non Linear workflow (suitable for Dev + QA environment)

Base build selection case 4: Auto selection of base build from the master branch

Percy project settings:

• Default base branch - master
• Auto-approve Branches - master or none (empty)
• Approval required branches - none (empty)
• NO PR

User Narrative: I am creating the builds in Percy without PR from multiple branches, keeping auto approval turned on for master branch mostly & not using approval required branch setting in any branch.

Which build is base build for QA Q1 branch build b3?

• Master branch - Build b2

Reason: As Percy perform comparison against base build selected from base branch set as master & QA Q1 branch fork point build in master, which is b2 in master branch.

Base build selection case 5: Auto selection of base build from master branch, while auto approving master branch builds but only latest approved build as base build from qa branch

Percy project settings:

• Default base branch - master
• Auto-approve Branches - master or none (empty)
• Approval required branches - qa
• NO PR

User Narrative: I am creating the builds in Percy without PR from multiple branches, keeping auto approval turned on for master branch mostly & also using approval required branch setting only for qa branch.

Which build is base build for QA Q2 branch build b3?

• Master branch - Build b3

Reason: As Percy perform comparison against base build selected from base branch set as master & QA Q2 branch fork point build in master, which is b3 in master branch.

Which build is base build for qa branch build b3?

• No base build

Reason: As Approval required branch is set to qa, which acts as a base branch also for itself & by definition it will select a base build which is approved, as there is no approved build thus no base build.

Base build selection case 6: Neither auto selection of base build from master branch, nor auto approving master branch builds but only latest approved build as base build from master branch

Percy project settings:

• Default base branch - master
• Auto-approve Branches - none (empty)
• Approval required branches - master
• NO PR

User Narrative: I am creating the builds in Percy without PR from multiple branches, keeping auto approval turned off for master branch always & also using approval required branch setting only for master branch.

Which build is base build for QA Q1 branch build b3?

• Master branch - Build b2

Reason: As Percy perform comparison against base build selected from base branch set as master & QA Q1 branch fork point build in master, which is b2 in master branch.

Which build is base build for master branch build b3?

• Master branch - Build b1

Reason: As Approval required branch is set to master, which acts as a base branch also for itself & by definition it will select a base build which is approved & b1 is the recent approved build.

Which build is base build for master branch build b5?

• Master branch - Build b4

Reason: As Approval required branch is set to master, which acts as a base branch also for itself & by definition it will select a base build which is approved & b4 is the recent approved build.

Base build selection case 7: Auto selection of base build from master branch, while auto approving master branch builds without approval required branch

Percy project settings:

• Default base branch - master
• Auto-approve Branches - master
• Approval required branches - none (empty)
• NO PR

User Narrative: I am creating the builds in Percy without PR from multiple branches, keeping auto approval turned on for master branch always & not using approval required branch setting for any branch.

Which build is base build for feature branch F3 - build b3?

• Master branch - Build b5

Reason: As Percy perform comparison against base build selected from base branch set as master & Feature F3 branch fork point build in master, which is b5 in master branch.

Which build is base build for feature branch F5 - build b3?

• Master branch - Build b5

Reason: As Percy perform comparison against base build selected from base branch set as master & Feature F5 branch fork point build in master, which is b5 in master branch.

Base build selection case 8: Auto selection of base build from master branch, while auto approving master branch builds without approval required branch

Percy project settings:

• Default base branch - master
• Auto-approve Branches - master
• Approval required branches - none (empty)
• PR & NO PR both

User Narrative: I am creating the builds in Percy with & without PR from multiple branches, keeping auto approval turned on for master branch always & not using approval required branch setting for any branch.

Which build is base build for feature branch F3 - build b3?

• Master branch - Build b5

Reason: As Percy perform comparison against base build selected from base branch set as master & Feature F3 branch fork point build in master, which is b5 in master branch.

Which build is base build for feature branch F5 - build b3?

• Feature F3 branch - Build b5 with PR

Reason: As Percy perform comparison against common ancestor (based on commit SHA) build, which is common build against PR target & PR origin, Feature F5 branch merge target is Feature F3 branch, Feature F5 branch has been rebased as well, so common ancestor (fork point) build is Feature F3 branch - Build b5. Also to note that if merge target is Feature F4 branch then common ancestor could have been Master b5.

Base build selection case 9:Auto selection of base build from master branch, while auto approving master branch builds but only latest approved build as base build from Feature F3 branch

Percy project settings:

• Default base branch - master
• Auto-approve Branches - master
• Approval required branches - Feature F3
• PR & NO PR both

User Narrative: I am creating the builds in Percy with & without PR from multiple branches, keeping auto approval turned on for master branch always & also using approval required branch setting only for Feature F3 branch.

Which build is base build for feature branch F3 - build b1 & b2?

• No base build

Reason: As Approval required branch is set to Feature F3, which acts as a base branch also for itself & by definition it will select a base build which is approved, as there is no approved build thus no base build.

Which build is base build for feature branch F3 - build b3?

• Feature F3 branch - Build b2

Reason: As Approval required branch is set to Feature F3, which acts as a base branch also for itself & by definition it will select a base build which is approved, as b2 is recent approved build in Feature branch F3 thus Feature F3 branch - Build b2.

Which build is base build for feature branch F5 - build b3?

• Feature F3 branch - Build b5 with PR

Reason: As Percy perform comparison against common ancestor (based on commit SHA) build, which is common build against PR target & PR origin, Feature F5 branch merge target is Feature F3 branch, Feature F5 branch has been rebased as well, so common ancestor (fork point) build is Feature F3 branch - Build b5. Also to note that if merge target is Feature F4 branch then common ancestor could have been Master b5.

Overriding the defaults

Setting the projects default base branch

If git projects default branch is different from master, you will want to update your Percy projects settings to mirror that. By default, Percy uses master as the default branch, but it’s not uncommon for teams to use a branch like develop as the main development branch.

To update this setting, you will need to go to your projects settings page: percy.io///settings Once you're on the settings page, look for a "Branch settings" heading and update the "Default base branch" input:

Read more about overriding the default base branch & troubleshoot here.