Skip to main content

Approval Workflow

Approve visual differences identified by Percy

Percy approval workflow is an important part of the visual review process. By following this guide, you can understand the different approval types and the request change feature provided by Percy, the concept of auto-approved branches, and how Percy effectively handles the approval workflow.

Approval types

Percy provides you granular control over the approval process. You can manage approvals in different ways:

  • Approve build
  • Approve groups of matching visual changes
  • Approve individual snapshots

Approve Build

Note: You can only approve snapshots, and not individual screenshots. This means that you can approve snapshots, which has screenshots captured across all browsers and width combination. However, it is not possible to approve individual screenshots taken on a specific browser for a specific width.

Approve Build

You can request changes if a snapshot is not yet ready for approval. By doing this, the build status will be changed to “Changes requested.”

Approve Build

Note: Once all snapshots in a build are approved, the whole build will be approved. If you have a source code integration installed, only marking a complete build as approved will mark your Percy check as “passed.”

Auto-approve branches

Auto-approve branches in Percy refer to a feature that enables specific branches in a version control system to skip manual approval and automatically pass visual reviews in Percy. Such branches will always be marked in green color, reducing false positives and saving your team time.

Note:

  • By default commits on “main” branch are marked as auto-approve branch.
  • This project setting enables teams to filter and auto-approve specific branches via regex. Auto-Approve Build
  • If there are any missing snapshots in the build, we do not auto-approve it.
  • If there are any failed snapshots in the build, it is currently auto-approved. If you prefer not to auto-approve, reach out to us to enable the validation flag for you.

How approvals are carried forward

Approved snapshots that were previously accepted will retain their approval status across builds throughout the lifespan of the branch. Essentially, identical snapshots will only require approval once per branch, as they are “carried forward.” For further information, refer to base build selection logic.

Note: This is only applicable for multi-branch or Git style workflow. If you are working on approval required branches workflow, you can refer to our Base snapshots selection.

How are builds approved

An example

Scenario 1: Snapshot exists in the main branch

Percy always compares first with the main branch, if there are differences, then it will check if the same differences were approved in the immediate previous build in same branch.

  1. Let’s consider a scenario in which you have a snapshot A in the main branch. The snapshot has a button which is blue in color.
  2. Create a feature branch (F1) from the main branch.
  3. Create Build 1 in F1. In this build, the color of button in snapshot A is changed from blue to green. In this case the build gets compared with the base build in the main branch and you approve the changes in Build.
    • Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
    • Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
  4. Next, create another build Build 2, in F1 . The snapshot in Build 2 remains exactly the same as the one in Build 1. In this case, the approval from Build 1 is carried forward to Build 2.
    • Pre state - 1 Changed, 0 Unreviewed, and 1: Approved.
    • Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
  5. Now, let’s say you create another build, Build 3 in which the button color changes from green to red. This snapshot has a change that is not approved in Build 2 in F1 and in the base build in the main branch. In this case, the approval is not carried forward.
  6. Now, a user requests changes in Build 3 to change the color red.
    • Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
    • Post state - 1 Changed, 1 Changed Requested, and 1: Approved.
  7. In the next build Build 4, the user changes the color from red to green, so the new Build 4 is submitted for review again. In this case also, the approval is not carried forward.
    • Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
    • Post state - 1 Changed, 0 Changed Requested, and 1: Approved.

Build Approval - Example 1

Scenario 2: Snapshot does not exist in the main branch

  1. Let’s consider a snapshot B which is not present in the base build in the main branch, you create a new feature branch (F2) and add a new feature on this branch in Build 1.
  2. This snapshot will be identified as a new snapshot in Build 1 and it will never be compared with main branch as the snapshot does not exist in the main branch.
  3. This new snapshot has a green color button and you have approved this snapshot.
    • Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
    • Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
  4. You create another build in the feature branch Build 2. The snapshot in Build 2 remains exactly the same as the one in Build 1. In this case, the approval from Build 1 is carried forward to Build 2.
    • Pre state - 1 Changed, 0 Unreviewed, and 1: Approved.
    • Post state - 1 Changed, 0 Unreviewed, and 1: Approved.
  5. Now, let’s say you create another build, Build 3 in which the button color changes from green to red. This snapshot has a change that is not approved in Build 2 in F2. In this case, the approval is not carried forward.
  6. Now, a user requests changes in Build 3 to change the color.
    • Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
    • Post state - 1 Changed, 1 Changed Requested, and 1: Approved.
  7. In the next build Build 4, the user changes the color from red to green, so the new Build 4 is submitted for review again. In this case also, the approval is not carried forward.
    • Pre state - 1 Changed, 1 Unreviewed, and 0: Approved.
    • Post state - 1 Changed, 0 Changed Requested, and 1: Approved.

Build Approval - Example 2

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Download Copy