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:

Permission	Access	Purpose
Repository: Contents	Read	Read manifests, READMEs, changelogs
Repository: Metadata	Read	List repositories and topics
Repository: Pull requests	Read	Track PR activity for insights
Organization: Members	Read	Sync organization membership

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 additional permissions:

Repository: Contents - Read & Write
Repository: Pull requests - Read & Write
Organization: Administration - Read

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