InfraStudio Agents Start free

Guides

Turn on Auto-merge

Let ready changes go on your product by themselves, safely, after a trial in shadow mode.

Last updated

After this guide, Auto-merge puts a ready change into your code by itself, and watches your product after it goes live.

Who can do it: a workspace admin or owner, or a person who may change everything in that product. See Roles.

What Auto-merge does

Auto-merge is an agent. It merges a pull request when the automatic tests passed and the review approved that same version of the change. Then it follows the deploy, and checks your product's health URL.

It starts off. It has two modes:

  • Shadow mode only says what it would put into your code, and changes nothing.
  • Live mode puts changes into your code, and they go on your product.

Live mode needs every readiness check to pass. One of the checks is a trial in shadow mode. So you always start in shadow mode.

Some files always wait for a person, in both modes. These are the files that the rules file of your repository names, and the paths that are always blocked. See The rules file below.

Step 1: set the repository rules

Auto-merge needs to know how your product is deployed and how to check it.

  1. Open the product's settings: Settings → Products, then Settings on the product's row.
  2. Open Technical settings → Repository rules.
  3. Fill in CI workflow name, Deploy job name and Health URL.
  4. Press Save in the bar at the bottom of the window.

Repository rules and privacy explains each field.

Step 2: choose the options

  1. In the product's settings, find Auto-merge in the part Agents, and open Options.
  2. Leave Mode on Shadow: only say what it would do.
  3. In Pull requests, choose The agents' own, or Also people's, with write access. The second one also takes a person's pull request that the PR reviewer approved. Pull requests from forks (copies of the repository on other accounts) are never taken.
  4. In At most this many changes a day, type a number from 1 to 10. The default is 3.
  5. In Minutes to watch your product after each change goes on it, type a number from 10 to 120. The default is 30. The next change waits until then.
  6. Press Save.

Step 3: turn it on in shadow mode

  1. Press the switch of Auto-merge.
  2. The window asks if you want to turn it on, and says that it is in shadow mode. Press Turn on.

Within a minute, the platform checks your repository. The list of readiness checks appears under Auto-merge.

Step 4: make every readiness check pass

Each check has a mark: ✓ passes, ✗ fails, or ! a warning. The checks are:

  • The repository can be read
  • The default branch is protected
  • Required status checks: GitHub requires checks before a merge.
  • CI passes on the default branch
  • The deploy job runs on merge
  • The ADLC policy is in the repository: the rules file. See below.
  • A health URL answers
  • Every pull request is reviewed: for people's pull requests, the PR reviewer must be on and review again after new changes.
  • Merge commits are allowed in the repository's settings on GitHub.
  • A track record in shadow mode: at least 3 times "would merge" in shadow mode, and no failed deploy and no pause of Auto-merge in the last 14 days.
  • GitHub's own auto-merge: a warning when GitHub's own auto-merge is allowed on the repository. A person who turns it on for a pull request merges it without these checks.

Each line says what the platform found.

Step 5: switch to live mode

When every check passes, the list says that live mode can be switched on.

  1. In Options of Auto-merge, choose Live: put changes into your code and on your product in Mode.
  2. Press Save.

If a check fails, the platform refuses live mode, and says which check to fix.

What you see when it worked

  • In shadow mode, Auto-merge says which pull requests it would put into your code.
  • In live mode, ready changes go on your product by themselves. The suggestion moves to the tab with your product's name.
  • The Agents page shows the mode beside Auto-merge.

After a failed health check

After each change, Auto-merge watches your product for the minutes you chose. If your product fails its health check twice in this time, Auto-merge turns itself off. It also opens a pull request that takes the change back. A person merges that pull request.

Auto-merge also turns itself off when a change it put into your code did not go on your product. The agent's row then says so. Look at what happened, then turn it on again.

The rules file

The rules file says which files always need a person's yes. Its name is .agents/adlc.json, on the default branch of your repository. ADLC is the name of these rules.

To add the platform's default file, press Add the ADLC policy to the repository under the readiness checks. The agents open a pull request with the file. Read it, change it if you want, and merge it.

The file looks like this:

{
  "version": 1,
  "manual_paths": [
    "(?i)(billing|payment|invoice|checkout)",
    "(?i)\\.(tf|tfvars|sql)$"
  ],
  "max_per_day": 3
}
  • version is always 1.
  • manual_paths is a list of up to 100 patterns (regular expressions). A pull request that changes a matching path is never merged by Auto-merge. A person merges it.
  • max_per_day is the most changes a day, from 1 to 10. It caps the option At most this many changes a day.

The file cannot remove the paths that are always blocked. These always need a person: CI, deploy and container files, migrations, dependency files, secrets and environment files, .agents/, CODEOWNERS, and the product's own Extra paths agents may never touch.

A pull request with the label no-auto-merge also always waits for a person.

More