CodeHerderSearch⌘KRequest access →

Converge a merge request 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.

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 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.
  • 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.

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.

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.

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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close