Fix a GitHub issue

In this tutorial, an agent fixes a bug from a GitHub issue, adds a test, and opens a pull request. You then check the pull request and review it like any other. It takes about 20 minutes. The examples use the repository acme/web and its issue 412; replace them with yours.

You need the Developer or Admin role in the organization; see Organizations and roles. You also need permission to install a GitHub App on the GitHub account that owns the repository, or an existing GitHub connection in Recursion. The repository should run its tests on pull requests, for example in GitHub Actions, so you can see them pass on the agent’s pull request.

Step 1: Connect GitHub

Connecting is an interactive authorization in GitHub, so do it in the console. It creates a connection for your organization but gives no agent access yet. Use the console or cURL.

Console
cURL

In the sidebar, click Integrations, then click Add integration.
Choose GitHub, then click Continue.
On GitHub, choose the account and select the repositories the connection may reach, including acme/web.
Back in Recursion, choose the account if asked. The connection appears under Integration connections.
Enable issue_read, get_file_contents, create_branch, push_files, and create_pull_request in the connection’s tool selection. New connections start with read-only tools selected.
Open the connection’s actions menu and click Test connection to confirm it can issue a token.

Connect in the console first, then list connections to get the connection id you’ll use in step 3.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/integrations/connections' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "connections": [
    {
      "connection_id": "31e6c9a4-2d75-48b0-a1f3-7c5e9d2b6a84",
      "organization_id": "org_01a08a705220724f9a2fe1bcd8638c9d",
      "provider": "github",
      "external_id": "58213377",
      "account_login": "acme",
      "account_type": "Organization",
      "resource_selection": "selected",
      "state": "active",
      "created_at": "2026-09-25T16:40:12Z",
      "updated_at": "2026-09-25T16:40:12Z"
    }
  ]
}

Continue when state is active.

Step 2: Create an environment

The agent works on GitHub through its GitHub tools, which run outside the sandbox, so the environment needs no GitHub network rules. New environments block all outbound traffic, which is fine for this task.

Console
cURL

In the sidebar, click Environments, then click Create environment.
Enter a Name, such as github-fixes.
Click Create environment.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/environments' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "github-fixes",
    "provider": "runs"
  }'

{
  "organization_id": "org_01a08a705220724f9a2fe1bcd8638c9d",
  "environment_id": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
  "name": "github-fixes",
  "scope": "organization",
  "provider": "runs",
  "computer_use": false,
  "created_at": "2026-09-25T16:44:03Z",
  "updated_at": "2026-09-25T16:44:03Z"
}

See Environments.

Step 3: Create the agent with GitHub access

Give the agent the GitHub tools it needs and access to only the repository it needs. The selected tools determine its short-lived token permissions. GitHub’s MCP tools run outside the sandbox; git and gh in the sandbox are not authenticated for GitHub.

Console
cURL

In the sidebar, click Agents, then click Create agent and choose Blank.
Enter a Name, choose a model, and paste the system value from the cURL tab into System prompt. Click Create agent.
On the agent’s Configuration tab, under Integrations, click Add integration access and select the GitHub connection.
Select issue_read, get_file_contents, create_branch, push_files, and create_pull_request under Tools.
Clear All authorized repositories, then select acme/web.
Click Use this access, then click Save new version.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Issue fixer",
    "model": "<model-id>",
    "system": "You fix GitHub issues with your GitHub tools.\nRead the issue and the code it touches, then find the cause of the bug.\nOn a new branch named fix/issue-<number>, commit the fix and a test that fails without it.\nOpen a pull request whose description starts with \"Fixes\" and the issue URL. Never commit to main.\nEnd with the pull request URL.",
    "nativeIntegrations": [
      {
        "connectionId": "31e6c9a4-2d75-48b0-a1f3-7c5e9d2b6a84",
        "permission": "write",
        "tools": ["issue_read", "get_file_contents", "create_branch", "push_files", "create_pull_request"],
        "resources": ["acme/web"]
      }
    ]
  }'

{
  "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
  "latest_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
  "name": "Issue fixer",
  "nativeIntegrations": [
    {
      "connectionId": "31e6c9a4-2d75-48b0-a1f3-7c5e9d2b6a84",
      "permission": "write",
      "resources": ["acme/web"]
    }
  ]
}

You can grant GitHub through a vault instead, which is useful when several agents share one grant. See GitHub and Vaults.

Step 4: Start the session

The opening message names the issue. The system prompt already says how to work: find the cause, commit the fix and a test on a new branch, and open a pull request.

Console
cURL

In the sidebar, click Sessions, then click Launch session.
Choose the Issue fixer agent and the github-fixes environment.
In Opening message, enter Fix https://github.com/acme/web/issues/412 and open a pull request.
Click Launch session.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Idempotency-Key: acme-web-issue-412' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
    "environment_id": "9d3e7b52-1a4c-4f80-b6e9-2c8a5d0f7e13",
    "message": "Fix https://github.com/acme/web/issues/412 and open a pull request."
  }'

The API answers 202 Accepted.

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status_path": "/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38"
}

The Idempotency-Key makes the start safe to retry: sending the same key again returns the same session instead of starting a second one.

Step 5: Wait for the session to finish

Watch the session in the console, or poll it until the agent’s turn ends.

Console
cURL

In the sidebar, click Sessions, then open the session.
Follow the transcript as the agent reads the issue and code, commits, and opens the pull request.
When the agent is done, its last message gives the pull request URL.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

A finished session looks like this. Some fields are left out here.

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status": "completed",
  "execution_state": "idle",
  "stop_reason": "end_turn",
  "updated_at": "2026-09-25T17:09:51Z"
}

What success means

The session’s stop_reason is end_turn, and the agent’s last message gives the pull request URL.
A pull request is open in acme/web from a branch other than main, its description starts with “Fixes” and the issue URL, and it adds a test for the bug.
A finished session doesn’t prove the work is right. Check the pull request and its checks before you merge. See What success means for other session states.

Step 6: Review the pull request

Open the URL from the agent’s last message, or list the repository’s open pull requests through the connection.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/integrations/connections/31e6c9a4-2d75-48b0-a1f3-7c5e9d2b6a84/repositories/acme/web/pull-requests?state=open' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "page": 1,
  "pull_requests": [
    {
      "number": 418,
      "title": "Escape quotes in search queries",
      "head_sha": "3f9c2e7a1b4d6e8f0a2c4e6b8d0f1a3c5e7b9d2f",
      "draft": false
    }
  ]
}

Review and merge it the way you would any contributor’s pull request.

What can go wrong

Symptom	Cause	Fix
The agent has no GitHub tools	The agent version has no GitHub access, or the session started from an older version.	Add integration access, save a new version, and start a new session.
The repository returns `404`	The GitHub App installation or the grant’s repository list doesn’t include `acme/web`.	Add the repository in GitHub and in the agent’s integration access.
Creating a branch or pull request is refused	The connection or agent lacks `create_branch`, `push_files`, or `create_pull_request`.	Enable those tools on the GitHub connection, then select them for the agent.
The pull request’s checks fail	The fix or its test is wrong.	Send a follow-up message with the failing check, and ask the agent to update the branch.
The agent stopped before opening a pull request	It hit a problem it couldn’t solve.	Read its last message, then send a follow-up message with what to do next.
The agent committed to the wrong branch	The system prompt didn’t forbid it strongly enough.	Keep “Never commit to main” in the system prompt, and protect `main` in GitHub.

Limits

A grant can list up to 500 repositories.
An agent can hold up to 25 integration connections.
See Limits for session and environment limits.

Next steps

GitHub

Permission presets, vault grants, and how GitHub tools work.

Automations

Start this agent when an issue is labeled.

Research team tutorial

Split a larger task across a team.

Environments

Network policy, setup scripts, and compute.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Fix a GitHub issue

Step 1: Connect GitHub

Step 2: Create an environment

Step 3: Create the agent with GitHub access

Step 4: Start the session

Step 5: Wait for the session to finish

What success means

Step 6: Review the pull request

What can go wrong

Limits

Next steps

GitHub

Automations

Research team tutorial

Environments

​Step 1: Connect GitHub

​Step 2: Create an environment

​Step 3: Create the agent with GitHub access

​Step 4: Start the session

​Step 5: Wait for the session to finish

​What success means

​Step 6: Review the pull request

​What can go wrong

​Limits

​Next steps

GitHub

Automations

Research team tutorial

Environments

Step 1: Connect GitHub

Step 2: Create an environment

Step 3: Create the agent with GitHub access

Step 4: Start the session

Step 5: Wait for the session to finish

What success means

Step 6: Review the pull request

What can go wrong

Limits

Next steps