Getting started

This guide takes you from nothing to your first merged change made by an agent. It takes about 30 minutes, most of it waiting for tests.

You need: a repository on your code host, admin access to it, and one coding agent you can start (the per-agent pages in docs/agents name the ones that have a guide).

Open Mergepace and sign in with your code host account. You land on the front page, which lists your repositories, grouped by project, with problems first.

If you don't see a repository you expect, it isn't connected yet. Go to step 2.

2. Install the app on a repository

Mergepace reads your repository and posts its results through an app you install on your code host (today, a GitHub App).

Open the install link from the front page, or from the repository's Setup tab.
Choose the organization or account, then pick the repositories.
Come back to Mergepace. The repository now shows on the front page.

Coming with #640: a one-command setup that does steps 2 and 3 for you. This section changes when it lands.

Next: open the repository and check its Setup tab.

3. Check Setup

Setup is a checklist. Each row is one thing Mergepace needs, with the button that fixes it. The rows, in order:

Installed: the app can read the repository.
Tests run on pull requests: Mergepace merges nothing until tests run on pull requests. If this row says no tests were seen, add your CI and open a pull request to try it.
Where tasks come from: the label on issues that agents may take (agent-ready by default).
Require the check: optional. Makes the Mergepace check a required check on the branch.
First agent: the agent you add in step 5.

Fix the first row that is not done. The button for it is the filled one.

Next: set the rules for who may merge.

4. Set merge rules

Open Rules on the repository. Rules decide which pull requests agents may merge on their own, and which need a person or a reviewer agent.

Failing or unfinished tests always block a merge.
Changes to risky files (sign-in, keys, merge rules, CI files) need an approval.
Everything else follows the rule you choose.

A repository that has never saved rules uses the server's default, and the page says so. Pick one of the ready-made sets, or read How to set merge rules for a solo owner. Nothing gets looser without a confirmation that lists what changes first.

Next: add an agent.

5. Add an agent

Open Agents and add one for the platform you use. Each platform has its own steps; the page shows them. In short:

Choose where the agent runs (for example, your agent tool's scheduled tasks, or a command-line agent on your machine; see docs/agents for per-agent steps).
Copy the one line shown, and run it or paste it where the page says.
The agent connects. Its status changes to Waiting for work.

Mergepace uses a name for each agent, such as builder-a. Keep the name the page gives you: it is how Mergepace tells agents apart.

If you use a command-line agent, the page also asks you to make an access key. The key is shown once. Copy it into the agent's environment; it works on this repository only. If you lose it, cancel it and make another.

Next: write a first task.

6. Write a first task

A task is an issue on your repository with the task label (agent-ready). Write it so an agent can start without asking you anything:

Add a link to the privacy page in the footer.

Paths: web/templates/footer.html, web/static/footer.css

Done when: the footer shows "Privacy" and links to /privacy, and the
page tests pass.

Paths: the files the agent may change. Mergepace uses them so two agents don't edit the same file at once. Always add this line.
After: #N: optional. The task waits until issue or pull request #N is done.

More on this in How to write a good task.

Next: watch it happen.

7. Watch it go through

Open the repository's Overview. Your task moves through these states:

Up next: the task is waiting for an agent.
Working now: an agent has taken it. The agent's claim renews while it works, so a silent agent loses the claim after a while.
On its way: the agent opened a pull request. Tests run on it.
Waiting for you or Ready to merge: tests have passed. The rules decide who approves next. If it needs people, it shows up under Waiting for you.
Merged: the pull request merged and the task closed.

If the pull request is ready and the rules allow an agent to merge it, Mergepace merges it itself, on the exact commit it checked. You can turn that off under Rules.

Next: check the Report after a few days, and read Concepts for what each state means.