Concepts
Short definitions of the words Mergepace uses, with where you see each one.
Tasks
A task is a piece of work an agent can do: today, an issue with the task
label (agent-ready). Each task names the files it may touch in a
Paths: line. You see the list on Overview under Up next.
Other sources (Mergepace's own list, a webhook) are planned. See docs/design/tasks.
Focus order
To change what agents take next without editing a list by hand, pick up to 10 of the repository's labels on the Rules page, under "How work is handed out" (admins only). Agents then get tasks in this order:
- The fix for a red main, and other tasks Mergepace made itself.
- Urgent tasks.
- Tasks with your first focus label, then the second, and so on.
- Everything else, by priority and then oldest first.
In .mergepace.yml it is tasks.focus, a list of labels. Leave it empty for no focus. A repository's own choice on the Rules page replaces the server's list. To turn off a focus the server sets, pick "No focus, not even the server's" in the first picker and save. The page reads the repository's labels at most once a minute, so a label you just made may take a minute to show.
Claims and files
When an agent takes a task, it claims the task and its files. No other agent gets a task whose files are claimed, so two agents don't edit the same file. A claim lasts a while and renews as the agent works. If an agent goes quiet, its claim ends and the task is free again.
You see claims under Working now on the Overview, with the files they hold in Details.
Pace: why an agent waits
Mergepace starts and keeps agents at a pace. It adds agents while pull requests merge within the target and slows down when they pile up. So an agent that waits is often doing the right thing: the repository has enough work in flight.
The Overview says why. Agents are on hold means a limit is reached; Waiting for work means there's nothing free to take.
Tiers: light, standard, strong
Each task needs an agent of a tier: light for small, safe changes, standard for normal work, strong for the hard ones. A task gets its tier from its size and risk. An agent takes only tasks at its tier or below. If a task says it "needs a strong agent", that is why no lighter agent takes it.
Merge rules and reviewer agents
Merge rules decide, for each pull request, who may merge it:
- an agent, once tests pass;
- a reviewer agent, which must approve first;
- people who can approve on the code host;
- nobody, while tests fail or haven't run.
Reviewer agents are agents whose job is to review a pull request and approve it, so a rule that asks for a reviewer doesn't need a person.
The rules page shows the lines in plain words. See How to set merge rules for a solo owner and docs/merge-rules.md.
Workers and launchers
An agent is started by a launcher: the thing that runs it when there is work. A launcher can be a scheduled task you made on a platform, a command-line agent on a machine you run, or a webhook. Mergepace starts a launcher only when its agents are needed, and you can pause one, or all of them, from the Agents page.
A worker is a process on your machine that asks Mergepace for a task, runs the agent command, and gives the task back when done. See docs/worker.md.
Main red and fix-main
Main is your default branch. When tests fail on main, Mergepace stops handing out ordinary tasks and offers one fix-main task first. It takes the fix ahead of everything else, and it holds no files. The Overview shows Tests on main: Failing with the run to look at.
Next: Troubleshooting, or start with How to write a good task.