# GitHub Evergreen: Configure CI Repair Without Losing Merge Control

Evergreen can repair selected pull requests, but its empty check list and existing auto-merge settings deserve attention before the first run.

By Paras Madan | 2026-11-16


GitHub Next's Evergreen repairs CI failures on pull requests you explicitly select. It does not directly merge them, but fixing their checks can let an existing GitHub auto-merge rule finish the job. Before enabling it, define what counts as ready and who still owns the final decision.

GitHub's [November 15 spotlight](https://github.github.com/gh-aw/blog/2026-11-15-ecosystem-spotlight/) brings attention to an existing project, not a newly released product. The useful question is how to adopt its repair loop without accidentally treating a green badge as permission to ship. This is a documentation and code review, not a deployment test.

## Start with the checks Evergreen must respect

The [base workflow](https://github.com/githubnext/evergreen/blob/main/workflows/evergreen.md) pairs `REQUIRED_CHECKS_JSON: '[]'` with `CHECK_GATE_MODE: configured`. That combination deliberately blocks readiness evaluation. An empty list is a setup placeholder, not a declaration that your repository has no requirements.

For a repository whose exact check names are `lint` and `unit-tests`, a proposed configuration is:

```yaml
REQUIRED_CHECKS_JSON: '["lint", "unit-tests"]'
CHECK_GATE_MODE: configured
```

Replace those illustrative names with the actual checks. The alternative `all-observed` mode uses an empty list and evaluates the checks it sees. That is a different policy: a check that never appears cannot be identified as missing by name. I would use named gates when the team already knows its required CI contract.

The current implementation accepts `SUCCESS`, `NEUTRAL` and `SKIPPED` as ready check conclusions. **Configured checks do not necessarily mean executed, passing tests.** Review whether skipped or neutral results are acceptable for each gate before relying on the ready label.

## Decide whether repair can lead to a merge

The [repository README](https://github.com/githubnext/evergreen) explicitly warns that existing auto-merge can merge a PR after Evergreen makes it green. Its ban on directly merging PRs does not switch that setting off.

Consider a dependency update with auto-merge already enabled. A repair fixes a type error, the checks complete, and GitHub may merge without another manual click. That can be exactly what the team wants. It is still a consequence to approve before selecting the PR, not something to discover from a production deployment notification.

If your intended workflow requires a person to inspect the repair, make that requirement part of the repository's actual merge controls. A sentence in an agent prompt is a poor substitute for an approval gate.

## Treat installation as a policy review

Evergreen's [installation guide](https://github.com/githubnext/evergreen/blob/main/INSTALL.md) asks the installer to inspect repository guidance, workflows, settings and the last 50 closed PRs, then confirm the inferred policy. It copies the workflow and shared policy files, compiles them with `gh aw compile`, and opens an installation PR.

Pay particular attention to permissions behind the `evergreen` label. The guide's defaults allow high-risk edits unless you restrict them. Public and fork PRs should remain metadata-only until a trusted approval covers the current head SHA. Also specify which CI jobs may be activated: the base CI-trigger function is a placeholder that needs an intentional implementation or disabling.

An installation PR that compiles successfully has answered a syntax question. It has not established that the chosen trust rules match your repository. Review those decisions before applying the label to real work.

## Require evidence after every write

Evergreen's [safe-output policy](https://github.com/githubnext/evergreen/blob/main/workflows/shared/evergreen/safe-output-policy.md) separates an attempted operation from a verified result. Comments, labels, workflow requests and branch pushes must be checked against GitHub state before the agent calls them complete. The agent cannot directly change the ready label or merge the base branch into the PR; readiness and branch freshness belong to the controller.

For a trial, ask for the resulting commit SHA, changed files and CI evidence, rather than accepting a message saying the fix should work. If the head changes while a repair is being prepared, require a fresh evaluation of that version. This keeps a useful patch from becoming a claim about code the agent never checked.

## Keep a failed repair from becoming an endless loop

The documented quota follows a PR across runs while its opt-in remains continuous; new commits alone do not reset it. Exhaustion stops work, requests removal of the opt-in, adds an exhausted label and leaves a short comment. Set the budget deliberately rather than assuming a scheduled run starts a fresh allowance.

Evergreen is most useful when a team can name its gates, trusted actors and stopping conditions. If those rules are still implicit, automating repairs will expose the ambiguity faster than it resolves it. Write down the decision you expect a human to make, then decide which part the workflow should be allowed to handle.

I’m Paras. I work at the intersection of AI, engineering and distribution.

I help technical teams turn complex AI workflows into clear developer stories that explain the decisions behind the product.

[Book a 30-minute call](https://cal.com/paras-madan/30min).
