Automate changes with MetergraphBot

MetergraphBot is a GitHub App that turns an approved recommendation into a pull request in your own repository. Installing it is optional. Recommendations and their evidence are there whether or not it ever touches your code, and you can always implement a change by hand.

A person approves. A person reviews. A person merges. MetergraphBot never merges anything.

What it does

When you approve a recommendation in the dashboard, MetergraphBot creates a branch, commits the change and the evidence behind it, and opens exactly one pull request per recommendation. Re-running lands on the same deterministic branch rather than piling up duplicates. If a route regresses, it can also open an issue.

The pull request goes to your repository, using the installation you granted. This is the one integration in Metergraph that is genuinely per-workspace.

Permissions it asks for

Permission	Why
contents:write	Create the branch and commit the code change and evidence files
issues:write	Open an issue when a route regresses
pull_requests:write	Open the pull request, reusing the same deterministic branch

Nothing else. It requests these scopes for the repositories you select, and no others.

Set it up

1. Send repository identity with your traces

   MetergraphBot can only propose a change to a file it can locate. That needs the repository on the captured rows, which the SDK sends from version 0.4 onward. Set it once:

   .env

   METERGRAPH_REPOSITORY=your-org/your-repo

   Or init(repository="your-org/your-repo"). Without it the SDK warns at startup and keeps capturing, but a recommendation built from those traces cannot be delivered.

2. Install the GitHub App

   Install MetergraphBot from its GitHub App page and choose all repositories or only selected ones, the same choice GitHub offers for any App. It acts only on what you grant.

3. Register the installation with your workspace

   Installing on GitHub is one half. Metergraph also has to record which installation belongs to which repository in your workspace, verify it, and release any deliveries that were waiting on it:

   Owner or member, authenticated by your dashboard session

   curl -X POST https://app.metergraph.dev/v1/github-installations \
     -H "Content-Type: application/json" \
     -H "Cookie: metergraph_session=..." \
     -d '{"repository": "your-org/your-repo", "installation_id": 12345678}'

   The installation id is the number in the URL of the App’s settings page for your organization.

4. Approve a recommendation

   Open the recommendation, read its evidence, and approve it. Owners and members can approve; a viewer can watch the status but not approve.

Step 3 has no button yet

There is no dashboard control that registers a GitHub installation. The endpoint exists and is authenticated by your dashboard session, so today it is a call you make yourself, from the browser or with your session cookie. Until it succeeds, an approved delivery sits at awaiting_bot_activation and no pull request is opened. If that step is not something you want to do by hand, ask Metergraph to register it for you.

Following a delivery

The recommendation shows its delivery status, and GET /v1/recommendations/{id}/delivery-status returns the same thing to any role, viewers included.

Status	Meaning
awaiting_bot_activation	Approved, waiting for a verified installation for that repository
pending	Queued for the bot
claimed	The bot is generating the pull request
retry	A transient failure. The next attempt time is on the row
blocked	Stopped for a stated reason, which the row carries
awaiting_pr_approval	The pull request is open and waiting for your review
recommendation_applied	The pull request was merged
declined	Closed without merging, or cancelled

Retries back off on a fixed schedule: 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, then every 24 hours, and they do not give up on their own. Cancel a delivery you no longer want with POST /v1/recommendation-deliveries/{id}/cancel.

When approval is refused

Approval returns a 409 with a reason rather than failing quietly:

Reason	What to do
not_recommended	The evidence did not reach a recommendation. There is nothing to deliver
no_samples	The analysis behind it has no source calls
legacy_protocol_traces	Some source traces came from an SDK older than v0.4 and carry no repository. Upgrade the SDK and capture again
mixed_repository	The source traces come from more than one repository, or from none. Metergraph will not guess which repository to change
unknown_recommendation	Wrong id, or it belongs to another workspace

Uninstalling

Revoke access from the App’s page in your GitHub organization or account settings. Automation stops immediately for the repositories you remove. Recommendations, evidence and captured traces are unaffected, and pull requests already open stay open for you to merge or close.

Run your first analysis Where recommendations come from in the first place.

See also

• Instrument a repository for setting repository identity across a codebase
• Manage your workspace for who can approve