# Converge a merge request before merge

Source: https://codeherder.com/docs/converge-an-mr-before-merge/

Wake a waiting task on CI results and comments, and send it back to a stage when its pull request fails CI, conflicts or needs work.

A pull request often needs several rounds before a person can merge it. CI fails, a bot reviewer finds a bug, you fix it, and CI runs again. You can let CodeHerder run that loop. A task waits for the result and wakes when something needs a fix. This page shows the pattern. It builds on [Waiting for a person to merge](https://codeherder.com/docs/waiting-for-a-merge/).

## What wakes a task

CodeHerder watches the task’s own pull request or merge request. It reads the state it already keeps, so you set up nothing on the git host. These events count:

- The CI runs at the current head commit all reached a final state. On GitHub, each workflow is one run. The wake comes when the last workflow ends.
- A new comment or review arrived. A comment from a bot that you set to **drop** does not count. A bot that you set to **collapse** does count. An approval never counts, with text or without. A review that asks for changes does count.

These events do not count: a run at an older commit, a request that belongs to another task, and a check that a third-party tool reports only as a status. See [Integrations](https://codeherder.com/docs/integrations/) for the bot rules.

Two features use these events:

- **A task that released itself to wait.** `ch sandbox release --wait` parks the task until new input arrives. A CI result or a new comment is now new input. The task wakes within a minute. If the retry finds nothing to do and the agent releases again, the task shows `blocked` with an “Awaiting input” blocker. It clears about five minutes after the CI result or comment arrives. See [Waiting for new input](https://codeherder.com/docs/task-not-moving/#waiting-for-new-input).
- **A merge-hold stage with `send_back`.** The task moves back to a stage when its request needs work. This feature is off until you set it. See the next section for what sends a task back.

## What sends a task back

Only a merge-hold stage with `send_back` moves a task. These causes send it back:

- A merge conflict, on GitHub or GitLab.
- A GitLab request that needs a rebase.
- A failed CI run at the head commit.
- A failed GitLab merged-result pipeline or merge-train pipeline.
- A removal from the host’s merge queue without a merge. CodeHerder treats it like a failed pipeline. On GitHub, it first checks the queue again. A request that is queued again or merged does not send the task back.
- A new comment or review, under the rules above.

These do not send it back: a request that is not approved, a draft, an unresolved thread, a queued merge train, and a green run. A merged-result or merge-train run that is still running holds the task. A newer green or running run replaces an older failure.

While every open request merges itself, a new comment does not send the task back. A request merges itself when GitLab auto-merge or a merge train is set, or when a merged-result run is still running. A conflict, a rebase need or a failed pipeline still sends the task back.

A hold stage without `send_back` never moves the task. A conflict then shows the “Conflicted, needs a decision” banner. See [Waiting for a person to merge](https://codeherder.com/docs/waiting-for-a-merge/).

## Set up the loop

You need three stages: the stage where an agent writes code, a read-only review stage, and the merge-hold stage.

**1. Create the review stage.** It has a prompt and no write access, so the agent reads and replies but changes no code:

```
ch stage create converge_review --stage '{"label":"Converge review","spec":{"prompt":"Read the CI result and every open thread on the task'"'"'s pull request. Reply to each thread with ch task comment <taskId> --to-host. If something needs a code change, move the task to code. If the request is clean, move the task to await_merge."}}'
```

**2. Create the merge-hold stage** if you have none. See [Set up a merge-hold stage](https://codeherder.com/docs/waiting-for-a-merge/#set-up-a-merge-hold-stage).

**3. Compose the workflow.** Put `converge_review` before `await_merge`. The send-back target must be an earlier stage than the merge-hold stage. Set `send_back` on the merge-hold instance:

```
{
  "key": "converge",
  "label": "Converge before merge",
  "instances": [
    { "name": "todo", "stage": "todo", "class": "todo" },
    { "name": "code", "stage": "code", "class": "doing", "to": ["converge_review"] },
    { "name": "converge_review", "stage": "converge_review", "class": "doing", "to": ["code", "await_merge"] },
    {
      "name": "await_merge",
      "stage": "await_merge",
      "class": "doing",
      "to": ["done", "converge_review", "code"],
      "send_back": { "to": "converge_review", "max_rounds": 3 }
    },
    { "name": "done", "stage": "done", "class": "done", "terminal": "success" }
  ]
}
```

```
ch workspace workflow edit converge --from-file composition.json
```

The `await_merge` stage lists `code` in its `to` list on purpose. A conflict needs a stage that can change code, and `converge_review` is read-only. See [Conflicts and failed merge pipelines](https://codeherder.com/docs/converge-an-mr-before-merge/#conflicts-and-failed-merge-pipelines).

CodeHerder refuses the file in these cases: `send_back` is on a stage that is not a merge-hold stage, `to` is not in that stage’s `to` list, `to` is not an earlier stage, `to` is terminal, or `max_rounds` is above 20. If you leave out `max_rounds`, the cap is 3.

## How a round runs

1. The agent in `code` opens the pull request and moves the task to `converge_review`.
2. The review agent reads CI and the threads. It replies on the host and either moves the task back to `code` or on to `await_merge`.
3. The task waits in `await_merge`. No agent runs there.
4. When a cause from the list above appears, the task moves back. Red CI, a failed merge pipeline or a new thread moves it to the `send_back` target, `converge_review`. Only a conflict or a rebase need goes to a stage that can write code, as the next section explains.
5. A green CI result alone does nothing. The task keeps waiting for a person to merge.

Each move back counts as one round. When the count reaches `max_rounds`, the task does not move. It becomes blocked, and the activity feed shows `Send-back rounds used up`. The blocker asks you to choose:

- **Send it back once more.** The task moves to the target stage so an agent can change the code.
- **Keep it at the hold stage.** The task keeps waiting. Only activity after that moment counts.
- Cancel the task.

You can also read the pull request and release the task. Use **Resolve** on the task page, or run `ch task unblock <blockerId>` with the blocker ID from `ch task blockers <taskId>`. Releasing the task starts a new watch from that moment, so older activity does not count again.

The round count does not reset. It counts every move from `await_merge` to one target stage over the life of the task. Each target has its own count. In the example, moves to `code` for a conflict and moves to `converge_review` for CI or comments are counted apart. A move by hand counts too. After the cap, the next new red CI result or thread blocks the task again. To allow more rounds, raise `max_rounds` in the workflow.

A task in `code` that has no more work can wait inside its own session:

```
ch sandbox release --wait --note "waiting for CI and reviewers"
```

## Conflicts and failed merge pipelines

Conflicts and failed merge pipelines take different routes.

A conflict or a rebase need goes to the nearest earlier stage that can write code, if the hold stage may move there. If there is none, it goes to the `send_back` target when that stage can write code. The example above sends a conflict to `code`. The activity feed shows `Sent back: merge conflict`.

A failed merged-result or merge-train pipeline does not look for a stage that can write code. It goes to the `send_back` target, like a red CI run at the head commit or a new comment. The example above sends it to `converge_review`. The activity feed shows `Sent back: merge CI failed`. A red CI run at the head commit or a comment shows `Sent back from merge hold`.

Before it moves the task, CodeHerder reads the git host again. If the request merged in the meantime, CodeHerder records the merge and moves the task on. If the host no longer reports the conflict, or is still checking, the task stays.

If no stage can write code for a conflict or a rebase need, CodeHerder does not move the task. It blocks the task, and the activity feed shows `No repair stage`. The blocker asks you to fix the workflow. Add a stage that can write code, such as `code`, to the hold stage’s `to` list. Then choose **I fixed the workflow**. The task returns to the hold stage and CodeHerder checks again. CodeHerder does not refuse a workflow that lacks such a stage when you save it, so check the `to` list yourself.

## Limits

- The check runs about every 30 seconds. A result can take up to a minute to act on.
- A push replaces the head commit. Runs on the old commit are ignored.
- `send_back` is set from the CLI. The web app keeps the setting when you save a workflow, but it has no control for it.
- A conflict or a rebase need sends the task back even if it began before the task entered the stage. Old threads and old CI results never do. Only activity after the task entered the stage, or after its latest release, counts.
- Tasks that run locally with `ch --local` do not send back for a conflict or a failed merge pipeline.

## Related guides

- [Waiting for a person to merge](https://codeherder.com/docs/waiting-for-a-merge/) for the merge-hold stage.
- [Integrations](https://codeherder.com/docs/integrations/) for comment mirroring and bot rules.
- [The stage library](https://codeherder.com/docs/stage-library/) for creating and composing stages.
- [Blockers and blocked tasks](https://codeherder.com/docs/blockers/) for what a blocker does.
