Setting up a project

1Connect your ticket board

Create a connection under your Notion connections and copy its internal token. Then open the database your tickets live in and share it with that connection — Notion hides everything you have not shared, so this is the step that makes your board visible at all.

MergeSmith then lists what it can see, you pick a board, and it asks which of your columns mean what: the title, the status, and which status value hands a ticket to the agent. That last one is the trigger.

You can add a second condition — most usefully a checkbox — so a ticket has to be moved and ticked. Without one, ordinary triage hands work to an agent by accident, which is a surprising way to learn what your board is for.

Live updates

Notion can tell MergeSmith the moment a ticket changes rather than being asked on a timer. The project page walks you through it while it is still to do; in Notion’s own dialog:

• Webhook URL — the address the project page shows you.
• API version — 2026-03-11.
• Events — clear all of them, then select only page.properties_updated and data_source.content_updated. The rest fire on every comment and every typo.

Notion then posts a verification token to that address. It arrives at MergeSmith rather than in your browser, so the project page has a button to go and look for it; paste it back into Notion’s Verify form to finish.

2Choose the repository

Pick from the repositories you granted when installing the App. If one is missing, install the App on it — there is a link on the step — and it appears.

MergeSmith reads the default branch here, which is what pull requests will target.

3Connect the agent

MergeSmith does not run the agent. It hands work to a routine you create, which holds your repository and your own credentials — so the code and the bill stay yours.

Create one for this repository, give it the prompt below, and paste its ID.

You are the implementation agent for MergeSmith.

Each time you are fired you receive one task as the trigger text. That text is
complete on its own: it carries the ticket, the repository, the branch, which
stage you are at, and exactly what to send back and where. Follow it literally.

- Do only what the task asks for at this stage. In a planning stage write no
  code and open no pull request. In an implementing stage follow the approved
  plan rather than re-deciding the approach.
- The task ends with a callback URL, a bearer token and a JSON shape. Sending
  that POST is not optional — it is the only way the run continues. Retry twice
  before giving up.
- If you cannot do the work, POST the "failed" stage with a clear reason.
  Silence strands the ticket and a person has to go and find out why.
- Where the task tells you to put a MergeSmith-Run-Id line in a pull request
  body, reproduce it exactly. It is how the pull request is matched to its run.
- If anything here conflicts with the task, the task wins.

It is short on purpose. Everything specific to a ticket — the plan, the branch, where to report back — is sent with every run, so the routine never has to know it in advance, and its last line says the task wins if the two ever disagree. A long routine prompt is a second copy of the contract that goes stale.

Press Test connection before moving on. It starts a session told to do nothing and stop, with an unreachable callback address, so a wrong key fails here rather than at three in the morning on your first real ticket.

4Say how it should behave

Whether the agent may ask questions, whether you approve plans, how many review rounds it gets, which labels go on the pull request, and what has to be true before a merge. All of it is on the settings page, and all of it can be changed later from Change settings.