Skip to main content
Every fix Peeps opens has already passed in your CI, but it still waits for a person to approve and merge it. While it waits, it holds one of the project’s Open fix pull requests places, and Peeps doesn’t fix that test again. On a busy suite those fixes pile up. This page covers three ways to move them along. The first one is recommended.

​
Approve by rule

Peeps never approves its own pull request. When a fix matches your rule, Peeps does two things:
  1. It adds the peeps:auto-approve label to the pull request.
  2. It turns on GitHub auto-merge with your chosen merge method.
A workflow in your repository then approves the labelled fix, and GitHub merges it once every rule on the branch is met, as it would for any pull request. Approve by rule works on GitHub. See GitLab for GitLab projects.

​
Which fixes match

A fix is approved by your rule only when all of these hold:
  • It changes how the test finds or waits for things, such as a locator, a wait or a page object. Peeps’ review classes every fix. A fix that changes what the test checks, such as an assertion or the test’s data, always waits for a person.
  • Its Peeps / fix verification check passed the first time on the pull request’s latest commit. A pass after a retry doesn’t count, and neither does a run whose retries your Peeps action doesn’t report, so use the latest version of the action.
  • It isn’t a draft. If Healed fixes arrive as is Draft pull request, no fix matches.
  • It merges into a branch you chose. By default that’s the headline branch. You can name other branches, and you can include fixes into an open pull request’s branch (see Fix a test on a pull request).
  • Every file it changes is under the project’s test root. This is on by default, and you can turn it off. There’s no limit on how many files a fix changes.
Peeps checks the rule when it posts the passing Peeps / fix verification check. If someone pushes to the fix’s branch after that, the next verification decides again.

​
Set it up

1

Turn on the rule

Open the project’s Repository settings page. Under Approve and merge Peeps fixes, check Approve and merge a Peeps fix when it matches this rule. Choose the branches, the merge method and the other options, then click Save rule. It takes Contributor or above.
2

Add the approval workflow

Click Add the approval workflow. GitHub opens .github/workflows/peeps-auto-approve.yml on your headline branch with the workflow already written. Commit it there.
3

Change two repository settings

In your repository’s Settings > General, turn on Allow auto-merge. In Settings > Actions > General, turn on Allow GitHub Actions to create and approve pull requests.
4

Require the fix verification check

In the ruleset for your headline branch, add Peeps / fix verification to the required status checks, so a fix can’t merge before Peeps has verified it.
The settings page lists these steps and marks each one that’s done. Peeps can’t read the Allow GitHub Actions to create and approve pull requests setting, or classic branch protection, so those items show as unknown. You’ll see the first in the workflow’s run if it’s off.

​
What the workflow does

  • It approves only Peeps’ own fixes. The pull request must have been opened by the Peeps app, from a peeps/ branch in your repository, and carry the peeps:auto-approve label.
  • It approves only a verified commit. The pull request’s latest commit must have a passing Peeps / fix verification check from the Peeps app itself. A check with the same name from anything else doesn’t count.
  • It never runs the pull request’s code. It runs on pull_request_target and never checks the branch out. Its token can only write pull requests and read checks.
  • A later push takes the approval back. If someone pushes to the fix’s branch, the workflow dismisses its approval unless Peeps verifies the new commit too. A person’s change then waits for a person’s review.
  • It only approves. Peeps turns on auto-merge as the Peeps app, because a merge made with the workflow’s own token starts none of your other workflows, such as a deploy on merge.
The workflow’s approval counts toward a required review like anyone else’s. A rule that needs a review from a code owner still waits for one. See Route reviews with CODEOWNERS.

​
When the merge doesn’t happen

  • Auto-merge is off in the repository. The label stays, and the fix waits for a person to merge it, or for Merge in Peeps.
  • Nothing is in the way. When a fix needs no review and no checks, GitHub won’t wait to merge it. Peeps then merges it at once, at the commit it verified.
  • A rule still isn’t met. Auto-merge waits, as it would for any pull request. The Fix pull requests tab shows what the fix is waiting on.

​
A ruleset bypass for the Peeps app

If your branch requires an approving review and you’d rather not run a workflow, you can add the Peeps app as a bypass actor on that ruleset. Merge in Peeps can then merge a ready fix without the review (see Merge from Peeps).
A bypass lets the Peeps app skip every rule in that ruleset, including required checks, for anything it pushes or merges. Prefer approving by rule, which keeps every rule in force.

​
Route reviews with CODEOWNERS

When fixes need a person, send them to the people who own the tests rather than to whoever owns the app code. Add your test root to CODEOWNERS with your QA team:
CODEOWNERS
Peeps’ fixes stay under the test root unless the fix belongs elsewhere, so they’re routed to that team.

​
Security notes

  • The rule can only approve fixes that Peeps’ review classed as changing how the test finds or waits for things, that passed the first time in your own CI, and that are still at the commit Peeps verified.
  • The workflow trusts the check by the app that posted it, not by its name.
  • Your branch rules still decide the merge. Approve by rule adds one approval and doesn’t skip any rule.
  • To stop, uncheck the rule and click Save rule. Fixes that already have the label keep auto-merge until you turn it off on the pull request or remove the workflow.

​
GitLab

Approve by rule isn’t available on GitLab yet. Until it is:
  • Merge from Peeps. Ready fixes have a Merge button in Peeps (see Merge from Peeps), which follows your project’s merge rules.
  • Route reviews. GitLab’s code owners (Premium) can send changes under your test root to your QA group, as above.