Skip to main content
TrustLens connects to GitHub using a GitHub App installation to scan repositories for AI agent configurations, MCP server definitions, and agent source code.

​
What TrustLens discovers

​
Agent configurations

Instruction and persona files used by AI coding assistants and orchestration frameworks:
  • AGENTS.md, CLAUDE.md, SKILLS.md, .cursorrules
  • CrewAI YAML configs (crewai.yaml, agents.yaml)
  • AutoGen and other framework config files

​
MCP servers

MCP (Model Context Protocol) server declarations and implementations:
  • MCP config files: mcp.json, .cursor/mcp.json, .vscode/mcp.json
  • Source code files implementing MCP servers via FastMCP, mcp.server, etc.

​
Agent source code

Source files that implement AI agents using popular SDKs:
  • CrewAI, OpenAI Agents SDK, AutoGen, LangChain, LangGraph, LlamaIndex, and others

​
Authentication model

TrustLens uses a GitHub App — not a personal access token — to access repositories. This provides:
  • Fine-grained repository access: the App is installed only on selected organizations or repositories
  • Short-lived tokens: installation access tokens expire after 1 hour and are auto-refreshed
  • Read-only by design: no write permissions are requested or required
  • Auditable: all API calls are attributed to the App, visible in your organization’s audit log

​
Required GitHub App permissions

PermissionScopeRequiredPurpose
contentsReadYesRead repository file trees and file contents for scanning
metadataReadYesList repositories accessible to the installation (auto-granted)
TrustLens only requires contents:read. No write permissions (contents:write, pull_requests, issues, etc.) are needed or requested. The App cannot create, modify, or delete any repository content.

​
Step-by-step setup

1

Create a GitHub App

  1. Go to your GitHub organization settings: Settings → Developer settings → GitHub Apps → New GitHub App
    • For a personal account: Settings → Developer settings → GitHub Apps → New GitHub App
  2. Fill in the required fields:
    • GitHub App name: neuraltrust-trustlens (or any name)
    • Homepage URL: your organization’s URL (e.g. https://neuraltrust.ai)
    • Webhook: uncheck Active (no webhooks needed)
  3. Under Repository permissions, set:
    • Contents: Read-only
    • Metadata: Read-only (auto-selected)
  4. Under Where can this GitHub App be installed?: select Only on this account (for your org) or Any account if you manage multiple orgs
  5. Click Create GitHub App
  6. Note the App ID (shown at the top of the app settings page)
2

Generate a private key

  1. In the GitHub App settings page, scroll to Private keys
  2. Click Generate a private key — a .pem file will be downloaded
  3. Keep this file secure — it is used to sign JWT tokens for authentication
The private key file looks like:
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----
3

Install the App on your organization or repositories

  1. In the GitHub App settings, click Install App
  2. Choose the organization (or user account) to install on
  3. Select All repositories or Only select repositories (choose specific repos to scan)
  4. Click Install
  5. Note the Installation ID from the URL: https://github.com/organizations/{org}/settings/installations/{installation_id}
4

Configure the integration in TrustLens

Provide the following credentials when creating a GitHub integration:
FieldValue
App IDThe numeric App ID from Step 1
Private KeyContents of the .pem file from Step 2
Installation IDThe numeric installation ID from Step 3
Optionally configure:
FieldDefaultDescription
Scan topics["agent", "mcp"]Filter which resource types to scan
Discover alltrueWhen true, scan all accessible repos; when false, only scan selected_projects
Selected projects[]List of owner/repo strings to scan (used when discover_all=false)

​
Incremental scanning

TrustLens stores the HEAD commit SHA for each scanned repository. On subsequent syncs, repositories whose HEAD SHA has not changed are skipped entirely — this dramatically reduces API calls and scan time for large organizations with many unchanged repositories.

​
Security considerations

  • Read-only access: TrustLens only requests contents:read. It cannot modify any repository content.
  • Scoped installation: install the App only on repositories you want to scan. You can adjust the installation scope at any time in your GitHub organization settings.
  • Short-lived tokens: installation access tokens expire after 60 minutes and are cached in Redis with a 55-minute TTL to avoid redundant token requests.
  • Private key security: store the private key securely (e.g. in a secrets manager). TrustLens encrypts it at rest in its database.

​
Troubleshooting

SymptomLikely causeResolution
No repositories discoveredApp not installed, or discover_all=false with empty selected_projectsVerify App installation and repository selection
401 UnauthorizedInvalid App ID, private key, or installation IDRegenerate private key and update credentials
Repository scan skippedHEAD SHA unchanged since last syncThis is expected incremental behavior — no action needed
403 Forbidden on file contentscontents:read permission not grantedRe-install the App and ensure Contents permission is set to Read