# How LeanAgent Creates and Manages GitHub Pull Requests for Proven Theorems

> Discover how LeanAgent automates GitHub pull request creation for proven theorems. Learn about its workflow from theorem detection to API-driven contributions.

- Repository: [LeanDojo/leanagent](https://github.com/lean-dojo/leanagent)
- Tags: how-to-guide
- Published: 2026-03-05

---

**LeanAgent automates the entire contribution workflow by detecting proven theorems, committing the changes to a temporary `_LeanAgent` branch, and opening a GitHub pull request via the REST API.**

LeanAgent, developed by lean-dojo, transforms formal theorem proving by automatically converting `sorry` placeholders into complete proofs and proposing these changes back to source repositories. When the proof search pipeline successfully verifies a theorem, the system executes a structured Git workflow to create and manage GitHub pull requests without manual intervention. This integration bridges the gap between automated reasoning and collaborative open-source development.

## Step-by-Step PR Creation Workflow

The implementation in [`leanagent.py`](https://github.com/lean-dojo/leanagent/blob/main/leanagent.py) orchestrates repository interactions through six distinct phases, each handled by dedicated utility functions.

### Determine the Repository Default Branch

Before creating any branches, LeanAgent queries the GitHub REST API to identify the target repository's default branch. The `get_default_branch` function (lines 46-58) sends a GET request to `/repos/:owner/:repo` and extracts the `default_branch` field, typically returning `"main"`. This ensures the subsequent pull request targets the correct integration branch.

### Create or Switch to the Temporary Branch

LeanAgent isolates all proof changes on a dedicated branch named `_LeanAgent`. The `create_or_switch_branch` function (lines 24-30) executes `git checkout -b _LeanAgent` to create the branch if absent, or `git checkout _LeanAgent` followed by a merge with the default branch if it already exists. This approach keeps the temporary branch synchronized with upstream changes while maintaining a consistent namespace for automated contributions.

### Commit the Proof Changes

Once `repo.change_sorry_to_proven` (defined in [`dynamic_database.py`](https://github.com/lean-dojo/leanagent/blob/main/dynamic_database.py)) replaces the `sorry` token with generated proof text, the `commit_changes` function (lines 32-40) stages the modifications. It first runs `git status` to verify the working tree contains changes, then executes `git add .` and commits with the standardized message `[LeanAgent] Proofs`. This function returns a boolean indicating whether a commit was necessary, preventing empty commits when no files changed.

### Push Changes to the Remote Repository

After successful local commits, `push_changes` (lines 42-45) executes `git push -u origin _LeanAgent` to publish the temporary branch to the remote repository. This establishes the tracking relationship required for the subsequent pull request creation and ensures the remote repository contains the proposed proof modifications.

### Open the Pull Request via GitHub API

The `create_pull_request` function (lines 60-78) constructs an authenticated POST request to `https://api.github.com/repos/:owner/:repo/pulls`. The request payload includes the PR title, body description, and specifies `_LeanAgent` as the `head` branch with the previously retrieved default branch as `base`. Authentication leverages the `GITHUB_ACCESS_TOKEN` environment variable. Upon successful creation, the function extracts the `html_url` from the JSON response.

### Record the PR URL for Persistence

Immediately after creating the pull request, LeanAgent stores the returned URL in the `Repository.pr_url` attribute (defined in [`dynamic_database.py`](https://github.com/lean-dojo/leanagent/blob/main/dynamic_database.py) lines 13-14). When the dynamic database serializes via `to_dict`, this URL persists as part of the repository metadata, creating a permanent record linking the proven theorem to its corresponding contribution.

## Integration with the Proof Search Pipeline

The PR creation workflow triggers automatically within the theorem proving pipeline. When `process_theorem_batch` successfully proves a theorem, it invokes `repo.change_sorry_to_proven` to update the local source files. LeanAgent then executes the complete Git workflow—branch management, committing, pushing, and PR creation—before the results are serialized to the dynamic database. While the primary training loop contains a commented invocation near line 1380, the integration point around line 627 demonstrates how the system bridges proof generation and repository contribution.

## Complete Workflow Implementation

The following example demonstrates the sequential execution of LeanAgent's PR management functions:

```python

# 1. Identify the target integration branch

default_branch = get_default_branch(repo_full_name)  # e.g., "main"

# 2. Prepare the isolated work branch

create_or_switch_branch(local_repo_path, "_LeanAgent", default_branch)

# 3. Commit proof modifications after replacing sorry tokens

if commit_changes(local_repo_path, "[LeanAgent] Proofs"):
    # 4. Publish branch to remote

    push_changes(local_repo_path, "_LeanAgent")
    
    # 5. Propose changes via GitHub API

    pr_url = create_pull_request(
        repo_full_name=repo_full_name,
        title="[LeanAgent] Automated Proof Contribution",
        body="This PR contains automatically generated proofs for previously incomplete theorems.",
        head_branch="_LeanAgent"
    )
    
    # 6. Persist the contribution URL

    repo.pr_url = pr_url

```

## Summary

- LeanAgent uses a dedicated `_LeanAgent` branch to isolate automated proof contributions from the default branch.
- The system authenticates with GitHub via the `GITHUB_ACCESS_TOKEN` environment variable to create pull requests through the REST API.
- Five utility functions in [`leanagent.py`](https://github.com/lean-dojo/leanagent/blob/main/leanagent.py) handle the complete workflow: branch detection, branch creation, committing, pushing, and PR creation.
- Successfully created pull request URLs are stored in the `Repository.pr_url` attribute and persist through the dynamic database serialization process.
- The workflow integrates directly with the `change_sorry_to_proven` method, creating a seamless pipeline from proof verification to open-source contribution.

## Frequently Asked Questions

### What branch naming convention does LeanAgent use for automated contributions?

LeanAgent consistently uses the branch name `_LeanAgent` for all automated proof contributions. The `create_or_switch_branch` function in [`leanagent.py`](https://github.com/lean-dojo/leanagent/blob/main/leanagent.py) (lines 24-30) creates this branch if absent or merges the default branch into it if it already exists, ensuring a standardized namespace that repository maintainers can easily identify and filter.

### How does LeanAgent authenticate with the GitHub API when creating pull requests?

Authentication occurs through the `GITHUB_ACCESS_TOKEN` environment variable. The `create_pull_request` function (lines 60-78) includes this token in the Authorization header when POSTing to the GitHub REST API endpoint `/repos/:owner/:repo/pulls`. This personal access token requires appropriate repository permissions to create branches and open pull requests.

### Where does LeanAgent store the URL of a successfully created pull request?

After the GitHub API returns the pull request data, LeanAgent extracts the `html_url` field and assigns it to `repo.pr_url`. This attribute is defined in the `Repository` class within [`dynamic_database.py`](https://github.com/lean-dojo/leanagent/blob/main/dynamic_database.py) (lines 13-14) and persists through the `to_dict` serialization method, ensuring the contribution link remains associated with the proven theorem in the database.

### Can developers disable the automatic pull request creation while testing proofs?

Yes. The primary training loop in [`leanagent.py`](https://github.com/lean-dojo/leanagent/blob/main/leanagent.py) contains the PR creation invocation around line 627, with an additional commented call near line 1380. Developers can disable automatic contributions by ensuring these calls remain commented or by omitting the `GITHUB_ACCESS_TOKEN` environment variable, which causes the GitHub API authentication to fail gracefully during testing phases.