How to Configure GitHub App Authentication in llama-github: A Complete Guide

To configure GitHub App authentication in llama-github, instantiate the GitHubAppCredentials dataclass with your App ID, private key PEM content, and installation ID, then pass it to the GithubRAG constructor to automatically generate installation access tokens for API calls.

The llama-github library supports both personal access tokens and GitHub App authentication for accessing the GitHub API. Configuring GitHub App authentication provides enhanced security through fine-grained permissions and automated token rotation, making it ideal for production deployments requiring organization-wide repository access.

Prerequisites for GitHub App Authentication

Before implementing GitHub App authentication in your codebase, you must complete the following setup steps in your GitHub organization or personal account:

1. Create a GitHub App in your organization or personal account settings.
2. Generate a private key for the app and download the PEM file.
3. Locate the App ID displayed on the app settings page.
4. Obtain the installation ID for the repositories where the app is installed (available on the App settings page or via the GitHub API).

Configuring GitHub App Authentication in llama-github

Basic Implementation with GitHubAppCredentials

The GitHubAppCredentials dataclass is defined in llama_github/github_rag.py. You must instantiate this class with the three required credentials and pass it to the GithubRAG constructor:

from llama_github import GithubRAG, GitHubAppCredentials

# 1️⃣ Fill in the credentials from your GitHub App

github_app_credentials = GitHubAppCredentials(
    app_id=123456,                     # <-- your App ID

    private_key="""-----BEGIN RSA PRIVATE KEY-----
MIIBOgIBAAJBAK... (rest of PEM) ...
-----END RSA PRIVATE KEY-----""",   # <-- the PEM content of the private key

    installation_id=987654321          # <-- the installation ID

)

# 2️⃣ Initialise the RAG client with the GitHub App credentials

github_rag = GithubRAG(github_app_credentials=github_app_credentials)

# 3️⃣ Retrieve context for a query (as usual)

context = github_rag.retrieve_context(
    query="How does the repo's CI pipeline work?",
    simple_mode=False
)

print(context)

When GithubRAG detects the github_app_credentials parameter, it automatically invokes GitHubAuthManager.authenticate_with_app from llama_github/github_integration/github_auth_manager.py to obtain a temporary installation access token and build an ExtendedGithub instance for all subsequent API calls.

Loading Credentials from Environment Variables

For production deployments, avoid hard-coding the private key in source control. Instead, load the PEM content from environment variables:

import os
from llama_github import GithubRAG, GitHubAppCredentials

github_app_credentials = GitHubAppCredentials(
    app_id=int(os.getenv("GITHUB_APP_ID")),
    private_key=os.getenv("GITHUB_APP_PRIVATE_KEY"),
    installation_id=int(os.getenv("GITHUB_INSTALLATION_ID"))
)

github_rag = GithubRAG(github_app_credentials=github_app_credentials)

Set the corresponding environment variables in your runtime environment:

export GITHUB_APP_ID=123456
export GITHUB_APP_PRIVATE_KEY="$(cat /path/to/private-key.pem)"
export GITHUB_INSTALLATION_ID=987654321

Authentication Method Precedence

The GithubRAG constructor accepts either a personal access token or GitHub App credentials, but never both simultaneously. If you supply both parameters, the GitHub App authentication takes precedence and the personal access token is ignored:

github_rag = GithubRAG(
    github_access_token="unused_if_app_provided",
    github_app_credentials=github_app_credentials
)

Internal Implementation Details

According to the llama-github source code, the authentication flow follows this execution path:

• llama_github/github_rag.py: Contains the GitHubAppCredentials dataclass definition and the initialization logic in GithubRAG.__init__ that detects which authentication method to use.
• llama_github/github_integration/github_auth_manager.py: Implements the authenticate_with_app method, which utilizes GithubIntegration to generate the installation access token from the provided App ID and private key.

The library handles token expiration automatically by generating fresh installation tokens as needed, eliminating the manual rotation required with static personal access tokens.

Summary

• GitHub App authentication requires three components: App ID, private key PEM content, and installation ID.
• Instantiate GitHubAppCredentials with these values and pass it to GithubRAG via the github_app_credentials parameter.
• The authentication flow is handled internally by GitHubAuthManager.authenticate_with_app in llama_github/github_integration/github_auth_manager.py.
• Store private keys in environment variables or secret managers rather than source code to maintain security.
• When both authentication methods are provided, GitHub App authentication takes precedence over personal access tokens.

Frequently Asked Questions

What is the difference between GitHub App and personal access token authentication?

GitHub App authentication uses short-lived installation tokens generated dynamically from a private key, providing automatic rotation and fine-grained repository permissions scoped to specific installations. Personal access tokens are static credentials that require manual rotation and grant broader access based on the user account permissions.

Can I use both authentication methods simultaneously in llama-github?

No, you should supply only one authentication method. If you provide both github_access_token and github_app_credentials to GithubRAG, the library prioritizes the GitHub App credentials and ignores the personal access token entirely.

Where should I store the private key PEM file?

Store the PEM content in a secure location such as environment variables, AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault. Never commit the private key to source control. The GitHubAppCredentials class accepts the PEM content as a string, allowing you to load it securely at runtime.

How do I find my GitHub App installation ID?

Navigate to your GitHub App's settings page in your organization or account settings. The installation ID appears in the URL when viewing a specific installation, or you can query the GitHub API using the GET /users/{username}/installations or GET /orgs/{org}/installations endpoints with proper authentication.

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