Skip to main content

GitHub Tool

Empower your agents to manage code, track issues, and automate workflows directly within your GitHub repositories.

This guide covers authenticating with a GitHub App, configuring permissions, and performing file operations.

💡 Core Concepts​

To configure this tool, you need to understand the authentication mechanism.

1. Why a GitHub App?​

Unlike personal access tokens, a GitHub App provides a secure, permission-scoped identity for your agent. It allows the agent to act as a "bot" user, ensuring your personal credentials remain private while giving the agent specific access to read code, write files, or manage issues.

2. Key Credentials​

  • App ID: A unique 6-digit number identifying your GitHub App.
  • Private Key: A secure certificate (.pem file) used to sign requests and prove the agent's identity.

⚙️ Configuration Steps​

Follow these steps to create your app and link it to SVAHNAR.

Create a GitHub App​

  1. Go to your GitHub Developer Settings and click New GitHub App.
  2. Name: Give your app a unique name (e.g., "SVAHNAR-Agent").
  3. Homepage URL: You can use your company URL (e.g., https://svahnar.com).
  4. Webhook: You can uncheck "Active" for now unless you have a specific webhook workflow.

Configure Permissions​

In the Permissions section of your app settings, grant the following access:

  • Repository permissions:
  • Contents: Read and Write (Required for reading/writing files)
  • Issues: Read and Write (Required for issue management)
  • Pull requests: Read and Write (Required for PRs)
  • Metadata: Read-only (Mandatory)
  • Commit statuses: Read-only

Install & Get Credentials​

  1. Install App: Go to the Install App tab in your sidebar and install it on the specific repository you want the agent to access.
  2. Get App ID: On the General tab, find and copy the App ID (e.g., 123456).
  3. Generate Private Key: Scroll down to "Private keys" and click Generate a private key. This will download a .pem file. Open this file with a text editor and copy the entire content (including -----BEGIN RSA PRIVATE KEY-----).

📚 Practical Recipes (Examples)​

Recipe 1: Basic Tool Configuration​

Use Case: Configuring the agent to access a specific repository.

tools:
  tool_assigned:
    - name: "GitHubTool"
      config:
        # The repository format must be "owner/repo_name"
        repo: "svahnar/docs-repo"
        
        # Your 6-digit App ID
        APP_ID: "123456"
        
        # Storing the PEM key in an environment variable is recommended
        PRIVATE_KEY: "${GITHUB_PRIVATE_KEY}"
        
        # Optional: Defaults to 'main' if omitted
        Branch: "main"

🚑 Troubleshooting​

  • "Resource not accessible by integration"

    • Ensure you have Installed the app on the specific repository (Step 3 above). Creating the app is not enough; it must be installed.
    • Check that your Permissions (Contents, Issues) are set to "Read and Write".

  • Authentication Failed

    • Verify the PRIVATE_KEY. It must include the header -----BEGIN RSA PRIVATE KEY----- and footer -----END RSA PRIVATE KEY-----.
    • Ensure the APP_ID matches the app you created.

  • File Not Found

    • Check the Branch in your configuration. If your repo uses master instead of main, you must specify it in the config.
    • Ensure the file_path includes the full relative path (e.g., src/components/App.tsx).