GitHub App Permissions

Shoehorn uses GitHub Apps for repository discovery, manifest reading, and workflow automation. Two apps are involved: the main Shoehorn app and the optional Shoehorn Forge app.

Why Two Apps

The main app is mostly read-only and handles discovery. The Forge app has write access for self-service workflows: creating repositories, scaffolding files, and opening pull requests. Separating them follows least privilege so most installations only need the main app.

Shoehorn App (Main)

The main app handles repository discovery, manifest reading, README fetching, ownership inference, and engineering insights.

Required Permissions

Read access to:

Permission	Purpose
Repository: Metadata	List repositories, read default-branch info
Repository: Contents	Read manifests (.shoehorn/**/*.yml), READMEs, changelogs (read covered via “code” below)
Repository: Custom properties	Read repository-level custom properties
Repository: Dependabot alerts	Surface dependency vulnerabilities per entity
Repository: Dependabot secrets	Sync Dependabot secrets metadata
Repository: Deployments	Show deployment history alongside entities
Repository: Issues	Track issue activity for engineering insights
Repository: Pull requests	Track PR activity for engineering insights
Repository: Secret scanning alerts	Surface secret-scanning findings per entity
Repository: Security events	Surface CodeQL and other security events
Repository: Actions	Read GitHub Actions run history
Organization: Members	Sync organization membership for team mapping
Organization: Administration	Discover org-level settings
Organization: Custom properties	Read org-level custom properties
Organization: Events	Subscribe to org-level events

Read and write access to:

Permission	Purpose
Repository: Administration	Manage repository settings the platform owns (topics, default branch, branch protection)
Repository: Code	Read repository contents; write only when an admin action explicitly changes a file

Required Webhook Events

Event	Purpose
push	Detect manifest changes on the default branch
repository	Discover new repositories, track deletions
pull_request	PR workflow events for insights and notifications

Configuration

After creating and installing the GitHub App, configure Shoehorn:

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

Store credentials in Kubernetes secrets:

kubectl create secret generic integration-credentials \
  --from-literal=github_app_id="123456" \
  --from-literal=github_app_installation_id="789012" \
  --from-file=github_app_private_key=private-key.pem

Shoehorn Forge App (Optional)

The Forge app powers self-service workflows: creating repositories, scaffolding files, opening pull requests, and triggering workflows.

Required Permissions

Read access to:

Permission	Purpose
Repository: Commit statuses	Check status of commits Forge has touched
Repository: Metadata	List repositories, default-branch info
Organization: Members	Resolve mold input that targets a team or user

Read and write access to:

Permission	Purpose
Repository: Administration	Create repositories, set topics, configure branch protection
Repository: Code	Scaffold and update files from mold templates
Repository: Custom properties	Set repository-level custom properties from molds
Repository: Pull requests	Open PRs for review-based scaffolding workflows
Repository: Actions	Trigger workflows defined in molds
Repository: Workflows	Write workflow files (.github/workflows/*.yml) from molds

Configuration

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

Store credentials in Kubernetes secrets:

kubectl create secret generic integration-credentials \
  --from-literal=github_forge_app_id="234567" \
  --from-literal=github_forge_installation_id="890123" \
  --from-file=github_forge_private_key=forge-private-key.pem

Creating a GitHub App

Step-by-Step

1. Go to your GitHub organization settings
2. Navigate to Developer settings > GitHub Apps > New GitHub App
3. Fill in the app details:

Setting	Main App	Forge App
App name	Shoehorn	Shoehorn Forge
Homepage URL	https://shoehorn.example.com	https://shoehorn.example.com
Webhook	(uncheck “Active”)	(uncheck “Active”)

4. Set the permissions as listed above
5. Click Create GitHub App
6. Generate a private key and download it

Installing the App

1. From the app settings page, click Install App
2. Select your organization
3. Choose All repositories or select specific ones
4. Click Install

Repeat for both apps if using Forge.

Permissions Summary

Capability	Main App	Forge App
Read manifests and READMEs	Yes	-
List repositories and topics	Yes	-
Sync org membership	Yes	Yes
Surface Dependabot, code scanning, secret scanning findings	Yes	-
Track PR, issue, deployment, Actions activity	Yes	-
Manage repository settings (topics, branch protection)	Yes	Yes
Create repositories	-	Yes
Create or update files	-	Yes
Open pull requests	-	Yes
Trigger and write workflow files	-	Yes

Helm Values

secrets:
  integrations:
    secretRef:
      name: integration-credentials
    keys:
      githubAppId: github_app_id
      githubAppInstallationId: github_app_installation_id
      githubAppPrivateKey: github_app_private_key
      githubForgeAppId: github_forge_app_id
      githubForgeInstallationId: github_forge_installation_id
      githubForgePrivateKey: github_forge_private_key

Rate Limiting

Configure the GitHub API rate limit budget:

GITHUB_RATE_LIMIT_PER_HOUR=1000    # Default
GITHUB_CONCURRENT_REPOS=5          # Max concurrent repo crawls
GITHUB_CACHE_TTL_MINUTES=15        # Cache TTL for API responses

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

See Also

• GitHub Integration - Full GitHub setup guide
• Repository Ownership - How ownership is established
• Forge Overview - Self-service workflows
• Forge Actions - Available Forge actions