Skip to content
Shoehorn

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

Section titled “Why Two Apps”

The main app has read-only access and handles discovery. The Forge app has write access for creating repositories and PRs. Separating them follows the principle of least privilege — most installations only need the read-only app.

Shoehorn App (Main)

Section titled “Shoehorn App (Main)”

The main app handles repository discovery, manifest reading, README fetching, and webhook processing.

Required Permissions

Section titled “Required Permissions”
PermissionAccessPurpose
Repository: ContentsReadRead manifests (.shoehorn/**/*.yml), READMEs, changelogs
Repository: MetadataReadList repositories, discover topics for ownership
Repository: Pull requestsReadTrack PR activity for engineering insights
Organization: MembersReadSync organization membership for team mapping

Required Webhook Events

Section titled “Required Webhook Events”
EventPurpose
pushDetect manifest changes on the default branch
repositoryDiscover new repositories, track deletions
pull_requestPR workflow events for insights and notifications

Configuration

Section titled “Configuration”

After creating and installing the GitHub App, configure Shoehorn:

Terminal window
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:

Terminal window
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)

Section titled “Shoehorn Forge App (Optional)”

The Forge app enables workflow automation: creating repositories, scaffolding files, and opening pull requests.

Required Permissions

Section titled “Required Permissions”
PermissionAccessPurpose
Repository: ContentsRead & WriteCreate files, scaffold project templates
Repository: Pull requestsRead & WriteCreate PRs for review-based workflows
Organization: AdministrationReadCreate repositories in the organization

Configuration

Section titled “Configuration”
Terminal window
GITHUB_FORGE_APP_ID=234567
GITHUB_FORGE_INSTALLATION_ID=890123
GITHUB_FORGE_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."

Store credentials in Kubernetes secrets:

Terminal window
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

Section titled “Creating a GitHub App”

Step-by-Step

Section titled “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:
SettingMain AppForge App
App nameShoehornShoehorn Forge
Homepage URLhttps://shoehorn.example.comhttps://shoehorn.example.com
Webhook(uncheck “Active”)(uncheck “Active”)
  1. Set the permissions as listed above
  2. Click Create GitHub App
  3. Generate a private key and download it

Installing the App

Section titled “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

Section titled “Permissions Summary”
CapabilityMain AppForge App
Read manifests and READMEsYes—
List repositories and topicsYes—
Sync org membershipYes—
Track pull requestsYes—
Create repositories—Yes
Create/update files—Yes
Create pull requests—Yes
Set repository topics—Yes

Helm Values

Section titled “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

Section titled “Rate Limiting”

Configure the GitHub API rate limit budget:

Terminal window
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

Section titled “See Also”