Skip to main content

GitHubTool

A multifunction GitHub tool to read, write, update, delete files, list files, create issues, and open pull requests in your provided repository.

Authentication​

Tool config must include repo (owner/repo), APP_ID and PRIVATE_KEY (GitHub App private key). Optionally provide Branch.

Operations​

  • read_file: Return file contents.
  • write_file: Create a new file (supply file_query).
  • update_file: Update file using update_file_query format.
  • delete_file: Delete a file.
  • list_files_in_bot_branch: List files in the bot branch.
  • Issue and PR operations are supported as well.

Usage​

  1. Create a Github App Follow the instructions here to create and register a Github app. Make sure your app has the following repository permissions:
  • Commit statuses (read only)
  • Contents (read and write)
  • Issues (read and write)
  • Metadata (read only)
  • Pull requests (read and write)
  • Once the app has been registered, you must give your app permission to access each of the repositories you whish it to act upon. Use the App settings on github.com here.
  1. Required parameters Before initializing your agent, the following environment variables need to be set:
  • GITHUB_APP_ID- A six digit number found in your app's general settings
  • GITHUB_APP_PRIVATE_KEY- The private key present in .pem file, full text of that file content as a string.
  • GITHUB_REPOSITORY- The name of the Github repository you want your bot to act upon. Must follow the format username/reponame. Make sure the app has been added to this repository first!
  • Optional: GITHUB_BRANCH- The branch where the bot will make its commits. Defaults to main.

YAML usage​

tools:
  tool_assigned:
    - name: "GitHubTool"
      config:
        repo: "owner/repo"
        PRIVATE_KEY: "${GITHUB_PRIVATE_KEY}"
        APP_ID: "123456"
        Branch: "main"

Invocation payload examples

Read a file

payload:
	operation: "read_file"
	file_path: "README.md"

Create a new file

payload:
	operation: "write_file"
	file_query: "/docs/newfile.md\nNew content here"

More details​

This tool uses a GitHub App private key for authentication. Keep keys secure and avoid embedding them directly in YAML stored in source control. Responses may include SystemMessage objects instructing the agent not to call the tool again when a write/create operation completes.

Agent integration example​

create_vertical_agent_network:
  agent-1:
    agent_name: "repo_agent"
    LLM_config:
      params:
        model: "gpt-4o-mini"
    tools:
      tool_assigned:
        - name: "GitHubTool"
          config:
            repo: "owner/repo"
            PRIVATE_KEY: "${GITHUB_PRIVATE_KEY}"
    agent_function:
      - "Perform repository read/write operations as requested."