GitHub Integration

The GitHub integration enables automatic repository discovery, manifest reading, README fetching, topic-based ownership, and optional Forge workflow automation.

Setup

Shoehorn connects to GitHub with GitHub Apps:

Shoehorn App - Required for discovery, manifests, READMEs, topics, and webhooks
Shoehorn Forge App - Optional for repository creation, file writes, PRs, and topic updates from Forge

Creating the Shoehorn App

Go to your GitHub organization settings
Navigate to Developer settings > GitHub Apps > New GitHub App
Configure the app:

Setting	Value
App name	`Shoehorn`
Homepage URL	`https://shoehorn.example.com`
Webhook URL	`https://shoehorn.example.com/api/v1/webhooks/github`
Webhook secret	Generate a random secret

Set permissions. The full list, including the security-scanning, deployment, and Actions read scopes used to surface findings per entity, lives on GitHub App permissions. The short version:
- Read access to repository metadata, contents, custom properties, Dependabot alerts and secrets, deployments, issues, pull requests, secret scanning alerts, security events, and Actions. Read access to organization members, administration, custom properties, and events.
- Read and write access to repository administration and code.
Subscribe to events:
- push - Detect manifest changes
- repository - New repository discovery
- pull_request - PR workflow events
Generate a private key and download it

Installing the App

From the app settings, click Install App
Select your organization
Choose All repositories or select specific ones

Configuring Shoehorn

Set these environment variables (or Kubernetes secrets):

GITHUB_APP_ID=123456
GITHUB_APP_INSTALLATION_ID=789012
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
GITHUB_ORGANIZATIONS=your-org

Manifest Discovery

The crawler automatically discovers manifests in repositories matching configured patterns:

# Default patterns
GITHUB_MANIFEST_PATTERNS=".shoehorn/**/*.yml,.shoehorn/**/*.yaml,catalog-info.yaml"

When a manifest is found:

The YAML is parsed and validated
An entity is created or updated in the catalog
The entity is linked to the repository
The search index is updated

Repository Ownership via Topics

Shoehorn can infer repository ownership from GitHub topics without a manifest.

Supported topic patterns:

Pattern	Example	Notes
`owner-<team-slug>`	`owner-platform-team`	Explicit ownership, highest topic confidence
`owner:<team-slug>`	`owner:platform-team`	Also supported
`team-<team-slug>`	`team-beta-team`	Team ownership, medium topic confidence
`team:<team-slug>`	`team:beta-team`	Also supported

If a manifest also declares an owner, the manifest wins.

README Discovery

READMEs are fetched and displayed on entity detail pages:

# Default patterns
GITHUB_README_PATTERNS="README.md,readme.md,Readme.md,docs/README.md"

Rate Limiting

Configure the GitHub API rate limit budget:

GITHUB_RATE_LIMIT_PER_HOUR=1000  # Default

The crawler distributes API calls across the budget to avoid hitting GitHub’s rate limits.

Forge App (Optional)

For Forge workflows that create repositories, push files, open PRs, or replace topics, create a separate GitHub App:

GITHUB_FORGE_APP_ID=234567
GITHUB_FORGE_INSTALLATION_ID=890123
GITHUB_FORGE_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."

The Forge app needs different permissions from the main app:

Read access to commit statuses, members, and metadata.
Read and write access to actions, administration, code, custom properties for repositories, pull requests, and workflows.

Full details on GitHub App permissions.

Webhook Events

When webhooks are configured, Shoehorn processes these GitHub events:

Event	Action
`push` to default branch	Re-scan manifests in affected repository
`repository.created`	Add to discovery queue
`repository.deleted`	Mark entities as orphaned