Skip to main content

Use the merge lane

The merge lane merges your tasks' pull requests for you. Without it, each task checks its own work and merges its own pull request. With it, each task hands its pull request to the project's lane and finishes; the lane tests the queued pull requests together, on the code as it will be after they merge, and merges the ones that pass. Your integration branch (such as develop) stays green, and many tasks can finish at once without waiting on each other's merges.

Who can do this: the lane is turned on for your organization by its plan. Getting one project ready for it needs the permission to edit that project; turning Read only off needs the permission to change its Settings › Branches.

Which plans include it​

The merge lane is a plan feature. It is included in the Team, Business and Enterprise plans, and in the Business trial. The Free plan and the Trial don't include it. Jaah can also turn it on or off for one organization, whatever its plan.

To change plans, see Change your plan. While your plan leaves it out, Audit shows no Merge lanes tab and tasks merge their own pull requests.

How a pull request goes through the lane​

  • It enters when a task opens its pull request: the task reports it to the lane, which lists it as Queued under Audit > Merge lanes. The task is then Done, and its worktree is free for the next task. A task that depends on it still waits: it shows merging under Depends on until the lane merges the pull request.
  • It is tested in a batch, with up to the project's Batch size of other queued pull requests, on the integration branch with all of them merged in. Its row reads Testing.
  • It leaves in one of these ways:
    • Merged: the batch passed, and the lane merged it.
    • Failed: the gate failed because of it, or it conflicts with the integration branch. See below.
    • Superseded: the pull request has a new commit (its task pushed one, or the lane joined a simple conflict for it), so a new row for that commit takes its place.
    • Closed: it waited in the queue too long and was sent back to its task to update, its task closed it, or the lane was stopped.

When a gate fails​

When a batch's gate fails, the lane works out which pull request broke it and fails that one; the pull requests that pass still merge.

  1. The failed pull request's row reads Failed, with what went wrong: Tests failed (and the tests that failed), Merge conflict, Branch behind or No forge login.
  2. Its task, already Done, opens again with the lane's verdict, so the agent sees the failure, fixes it and pushes.
  3. The pushed fix queues again and goes through a later batch.

A conflict where both sides only add lines, such as two pull requests each adding a row to the same table, reopens no task: the lane joins both and tests the result.

If the integration branch itself goes red, a red icon on the project's merge lane (Audit > Merge lanes, project picked) names the failing tests and the task the lane filed to fix them. People who can edit the project get a Merge fix filed notification when they turn it on in their profile. Queued pull requests wait until it is fixed; one that fixes part of it and breaks nothing still merges. A test that fails only sometimes gets its own Fix flaky test task and is listed under Flakes.

Turn on the merge lane for a project​

With the lane in your plan, it runs for each project that has it ticked, a repository on GitHub, GitLab or Azure DevOps, and may push to it. It is off for a project until ticked. Bitbucket can't merge a pinned commit, so it has no lane. To turn it on:

  1. In the sidebar, select Directory, then the Projects tab.
  2. Select the project's name to open its settings.
  3. On General, check that the Repository line lists a repository on GitHub, GitLab or Azure DevOps.
  4. Select the Settings tab, then Branches. Check that Read only is off, so tasks may push. With more than one repository, pick the primary one in Repository first.
  5. Select Merge lanes and tick it. Optionally, set Batch size: how many pull requests the lane tests and merges together. Smaller batches find a failing pull request sooner; larger ones merge more at once.
  6. Select Save.
  7. Select Audit > Merge lanes, then pick the project in the Project filter. Its green dot, at the end of the lane's tabs, reads Active when you point at it. No Merge lanes tab, or no lane for the project, means it can't use the lane yet: check steps 3 and 4. A project that used the lane before keeps its lane, and its dot says why the lane is off, with a link to the fix, such as Turn on Push.

Tasks already running when the lane comes on are told to report their open pull requests to it. New tasks use the lane from the start.

Turn it off​

The lane goes off for every project when your plan stops including it, or for one project when its Read only is turned on or its repository is removed. A lane that still has queued pull requests reads Draining: they merge first. To end that now, select the Stop lane icon on the project's lane under Audit > Merge lanes: it stops the lane's run, closes the queue and tells each task to merge its own pull request.