GitHub Integration

Overview

Converra creates pull requests in your GitHub repos when optimizations find improvements. Connect your GitHub, map prompts to files, and optimization winners are delivered as PRs with metrics, evidence, and a one-click merge path.

Think of it as Dependabot for your AI agents.

What It Does

• Auto-PR on completion — when an optimization finds a winner, Converra opens a PR with the updated prompt file
• Metrics & evidence — each PR body includes a head-to-head metrics table, evidence summary, and link back to the optimization
• Check runs — a GitHub check run is attached with pass/fail status tied to the optimization outcome
• Labels — PRs are tagged converra:optimization and converra:auto-pr for easy filtering
• Auto-superseding — if a newer optimization completes for the same prompt, the old PR is closed and replaced
• Merge-back sync — when you merge the PR, Converra updates the prompt status automatically

Setup

1. Install the GitHub App — go to Integrations in the Converra app and click Connect GitHub. Select which repos to grant access to.
2. Map prompts to files — Converra auto-detects prompt files in your connected repos. You can also map them manually from the prompt settings page.
3. Run an optimization — when a winner is found, a PR appears in your repo with the diff, metrics, and evidence.

What's in the PR

Each pull request includes:

Section	Contents
Title	Prompt name + optimization summary
Metrics table	Head-to-head lift, goal achievement, sentiment, clarity with deltas vs baseline
Evidence summary	Number of simulations, persona coverage, statistical confidence
Check run	GitHub check with pass/fail tied to optimization outcome
Labels	converra:optimization, converra:auto-pr
File diff	The actual prompt file change

Manual PR Creation

You can also create PRs manually for any completed optimization via the API:

curl -X POST https://converra.ai/api/v1/optimizations/{id}/github-pr \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "your-org",
    "repo": "your-repo",
    "filePath": "prompts/support-agent.txt",
    "baseBranch": "main"
  }'

Or via the SDK:

const pr = await converra.optimizations.createGitHubPR(optimizationId, {
  owner: "your-org",
  repo: "your-repo",
  filePath: "prompts/support-agent.txt",
  baseBranch: "main",
});
console.log(pr.url); // https://github.com/your-org/your-repo/pull/42

Auto-PR Settings

Configure automatic PR creation from the prompt settings page or the Integrations page:

Setting	Options	Default
Auto-PR	On / Off	Off
Target repo	Any connected repo	—
File path	Path to prompt file in repo	Auto-detected
Base branch	Branch to open PRs against	main

When auto-PR is enabled and an optimization completes with a winner, Converra opens the PR automatically without manual intervention.

Webhook Events

If you use Converra webhooks, the following events fire for GitHub PR activity:

• github.pr.created — a new PR was opened
• github.pr.merged — a PR was merged (prompt status updated)
• github.pr.superseded — an older PR was closed because a newer optimization completed

FAQ

Do I need to change my repo structure?

No. Converra works with any file path you point it at. The prompt file can be .txt, .md, .json, or any text format.

What happens if I close the PR without merging?

Nothing changes in Converra. The optimization result stays available and you can create a new PR later or apply the variant manually.

Can I use this with monorepos?

Yes. Map each prompt to its specific file path within the monorepo. Multiple prompts can point to different files in the same repo.

What permissions does the GitHub App need?

The Converra GitHub App requests: Contents (read/write for creating branches and commits), Pull requests (read/write for opening PRs), Checks (read/write for check runs), and Metadata (read for repo info).