> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pull request review flow

> How Greptile, human review, CI, and automerge work together on OpenSRE PRs.

This page is the contributor map for what happens after you open a pull request:
Greptile review, required CI, human maintainer judgment, and the optional
`automerge` label.

Greptile and automerge help maintainers move the queue. They do **not** replace
maintainer approval.

## The short path

1. Open a focused PR with the [PR template](https://github.com/Tracer-Cloud/opensre/blob/main/.github/PULL_REQUEST_TEMPLATE.md) filled in.
2. Leave **Allow edits from maintainers** enabled on fork PRs.
3. Wait for CI (the required check is **CI Gate**).
4. Trigger Greptile and work to **Confidence Score: 5/5** with **zero unresolved** threads.
5. A maintainer reviews and either merges, asks for changes, or adds the `automerge` label when the PR is ready to land on its own.

Full contribution rules: [CONTRIBUTING.md](https://github.com/Tracer-Cloud/opensre/blob/main/CONTRIBUTING.md).
Local checks before you push: [CI.md](https://github.com/Tracer-Cloud/opensre/blob/main/CI.md).

## Greptile (AI review)

OpenSRE uses [Greptile](https://greptile.com) for automated review. Opening or
reopening a PR posts a reminder comment. Greptile is a **human gate**: aim for
**5/5** before you ask a maintainer to merge or add `automerge`.

**Trigger a review** with a PR comment:

```text theme={null}
@greptile review
```

Give it about **5–10 minutes** (sometimes longer). Fix the feedback, resolve
threads you have addressed, then comment `@greptile review` again until you
reach **5/5** with no open threads.

Optional: the [greploop skill](https://skills.sh/greptileai/skills/greploop)
can run that loop for you.

Treat Greptile comments like normal review. Reply and leave a thread open only
when you need a human decision.

## CI

Required checks must be green before merge. The branch-protection aggregator is
**CI Gate** (quality + unit tests). Some paths also run Interactive Shell Live
checks — those must pass when they are required for your change.

If CI is red, fix the branch before asking for another Greptile or maintainer
pass. Do **not** open a test-only or CI-only PR just to chase failures that are
already red on `main` unless a maintainer asked for that work — see
[CONTRIBUTING.md](https://github.com/Tracer-Cloud/opensre/blob/main/CONTRIBUTING.md).

## Human review

A maintainer decides when the PR is ready. Greptile 5/5 and green CI are
necessary signals, not a merge button.

Expect maintainers to look at:

* Problem statement and proof in the PR body (demo, screenshot, or log)
* AI-usage disclosure when you used AI assistance
* Scope (one concern per PR; no refactor-only drive-bys)
* Tests for behavioral changes

Keep the **PR description** current when the problem, solution, or evidence
changes. Comments are for discussion; the body is what reviewers re-read.

Need help coordinating? Ask in Discord
[#contribute](https://discord.gg/opensre).

## Automerge (maintainer opt-in)

The `automerge` label is **maintainer-applied** after Greptile and human review
are done. Contributors should not add it themselves unless a maintainer asks.

When a PR has `automerge` and is otherwise ready, automation squash-merges it
into `main` and deletes the branch.

### What automerge waits for

* PR targets `main`, is open, and is not a draft
* Required CI (and other non-skipped checks) are green
* The branch is mergeable

Greptile’s own check status is **not** what automerge waits on — maintainers add
the label only after Greptile and human review are finished.

### When the branch is behind `main`

Branch protection requires PRs to be up to date with `main`. Automerge only
merges when GitHub reports the PR as mergeable. A behind branch usually stays
stalled until someone clicks **Update branch** (or rebases onto `main`) and CI
goes green again — including for PRs that already have the `automerge` label.
Automerge does **not** refresh the branch for you today.

### Paths that never auto-merge

PRs that touch these paths always need a **human** to press merge, even with
`automerge`:

| Prefix               | Why                     |
| -------------------- | ----------------------- |
| `core/`              | Agent runtime           |
| `platform/`          | Multi-tenant platform   |
| `gateway/`           | Chat / gateway surfaces |
| `.github/workflows/` | CI and merge machinery  |
| `.github/scripts/`   | Merge machinery         |

Automerge lists every changed file via the GitHub API (including rename origins).
If fewer file entries come back than the PR’s changed-file count, it refuses and
asks for a human — so a protected-path change cannot hide behind a partial list.

Docs, tests, integrations, and most surface changes can still use automerge when
a maintainer labels them.

## Improve a PR during review

1. Read Greptile and maintainer comments as the action list.
2. Push fixes; update the PR description when the story or evidence changed.
3. Resolve threads you have addressed.
4. Re-run `@greptile review` only after the branch and description are current.
5. Keep discussion on the PR when possible; use Discord when you need maintainer
   coordination or think automation is stuck.

## When things stay quiet

* Greptile can take several minutes; do not spam `@greptile review`.
* Automerge only runs for the `automerge` label and green checks.
* If CI is pending, wait for the next green run.
* If the PR is behind `main`, update the branch (or ask a maintainer), then wait
  for CI again.
* If a maintainer is actively editing the branch, let them finish before
  pushing competing commits.

Still blocked after CI is green and Greptile is 5/5? Ping in
[#contribute](https://discord.gg/opensre) with the PR link and what you are
waiting on.