MergeSmithDocs

Running MergeSmith on your own machine

MergeSmith is only reachable from this computer. This gives it a fixed address on the internet, which is what GitHub and the agent need to reach it.

Why it is needed

Two things have to reach MergeSmith from outside: GitHub, when a pull request opens or a check finishes, and the agent, when it has a plan ready or has pushed code. Neither can reach localhost.

Nothing warns you about this, which is what makes it worth the trouble. Signing in works, connecting Notion works, approving a plan works — and then the run sits in implementing forever, because the message saying it had finished had nowhere to go.

What you need

  • A free Cloudflare account.
  • A domain whose DNS Cloudflare manages. This is the part people get stuck on: a named tunnel publishes on your own domain, so there has to be one. A subdomain of a domain you already own is fine — mergesmith.yourdomain.com — and costs nothing extra.

If your DNS is somewhere else

A tunnel route creates a CNAME to <tunnel-id>.cfargotunnel.com, and that target only resolves through Cloudflare’s proxy. So the zone has to be on Cloudflare — a record at Google Cloud DNS or Route 53 pointing at it will not work.

The obvious idea — add just mergesmith.example.com to Cloudflare and delegate it with an NS record — does not work. Adding a subdomain as its own zone is an Enterprise feature, and the dashboard refuses it with please ensure you are providing the root domain and not any subdomains. The API refuses it too. Worth saying plainly, because the delegation itself is a normal DNS thing and it is not obvious that the Cloudflare half of it is gated.

That leaves three real choices.

  • Register a domain at Cloudflare. Registrar sells at cost and puts DNS on Cloudflare automatically, so a named tunnel works immediately. If you were going to buy a domain for this anyway, this is the whole job in one step.
  • Move an existing domain’s nameservers to Cloudflare. Free, and the registrar can stay where it is — but it moves all DNS for that domain, including whatever serves your live site. Check the records Cloudflare imports before switching.
  • Use a quick tunnel until you have a domain. Below.

The stopgap: a quick tunnel

One command, no account, no domain. It gives you a working public address in seconds, which is enough to connect GitHub and Notion.

It will not get you a plan back

A cloud agent runs on somebody else’s network, and those networks commonly refuse to connect to trycloudflare.com — it is a free shared host, so it is on the wrong lists. The refusal is a policy denial at their proxy, which no setting here can change.

Webhooks still arrive, so everything looks connected: a ticket starts a run, the agent is fired and does the work. Then it tries to report back, cannot, and cannot even tell you it could not — so the run sits in planning with the last thing that went right still on screen. Use a named tunnel on your own domain for anything past that.

cloudflared tunnel --url http://localhost:3111

It prints something like https://random-words-here.trycloudflare.com. Put that in MERGESMITH_APP_URL and skip the rest of this page.

The catch:that address changes every time cloudflared restarts, and it is written into the GitHub App at creation — so each restart means editing the App’s webhook and callback URLs by hand. Fine for getting started, tiresome as a habit, which is why the named tunnel below exists.

1Create the tunnel

In the Cloudflare Zero Trust dashboard, go to Networks → Tunnels and create a tunnel of type Cloudflared. Give it a name — MergeSmith does nicely.

2Run the connector on your machine

Cloudflare shows you an install command containing a long token. Run it on the machine MergeSmith runs on. On Windows it installs cloudflared as a service, so it starts again with the computer.

Back on the tunnel’s Overview tab you should see Active replicas: 1 and status Healthy. That means the connector is talking to Cloudflare. It does not yet mean anything is being served — Routes will still read 0.

3Add a route, so the tunnel knows what to serve

This is the step that is easy to miss. A healthy tunnel with no routes reaches Cloudflare and serves nothing.

Press Add a route and choose Published application — the first of the four options. The others are for private networking and are not what you want here.

Fill it in like this:

  • Subdomain — mergesmith
  • Domain — pick your domain from the list
  • Path — leave empty
  • Type — HTTP
  • URL — localhost:3111

HTTP rather than HTTPS is right here: the connection from Cloudflare to your machine is already inside the tunnel, and MergeSmith serves plain HTTP locally. Visitors still get HTTPS.

Save it. Routes becomes 1, and Cloudflare creates the DNS record for you.

4Check it from a browser

Open https://mergesmith.yourdomain.com. You should get MergeSmith. If you get a Cloudflare error page instead, the route is pointing at the wrong port — the URL must match the port MergeSmith is actually running on.

5Tell MergeSmith its address

Put the hostname in apps/web/.env.local:

MERGESMITH_APP_URL=https://mergesmith.yourdomain.com

Restart MergeSmith. This page will stop telling you to do any of this, which is how you know it worked.

Do this before you create the GitHub App

The address is written into the GitHub App when it is created — it becomes the App’s webhook URL and its sign-in callback. Create the App while the address is still localhost and GitHub will keep trying to deliver events there forever.

If you already did:open the App’s settings on GitHub and replace two fields by hand — the Webhook URL with <your address>/api/webhooks/github, and the Callback URL with <your address>/api/auth/callback/github. Because this address does not change, that is the last time you will have to.

The same thing from a terminal

If you would rather not use the dashboard, these four commands do all of the above.

cloudflared tunnel login
cloudflared tunnel create mergesmith
cloudflared tunnel route dns mergesmith mergesmith.yourdomain.com
cloudflared tunnel run --url http://localhost:3111 mergesmith

The third command is the one that corresponds to adding a route. Skipping it leaves you with the healthy tunnel that serves nothing.

If events still are not arriving

  • Routes still says 0. The tunnel is connected but has nothing to serve. Step 3.
  • Your address loads nothing.The route’s URL is pointing at the wrong port, or MergeSmith is not running.
  • The site loads but GitHub events do not arrive.Check the App’s webhook URL matches your address. Under Advancedon the App’s settings page, GitHub lists recent deliveries and the response each got.
  • Active replicas is 0. The connector has stopped. On Windows, check the cloudflared service is running.