How LeanAgent Creates and Manages GitHub Pull Requests for Proven Theorems

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 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) 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 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:

# 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 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 (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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}