GitHub App for self-hosted profile generation

[danielbodnar]

Summary

Create a GitHub App that installs into a user's account and generates a profiles-sh repository with GitHub Actions for self-hosted profile generation, caching, and rendering.

Motivation

Currently, profiles.sh fetches and computes everything server-side on each visit (with caching). A GitHub App approach would:

• Reduce API pressure: GitHub Actions run authenticated as the user's installation, with higher rate limits
• Enable offline/self-hosted: Users own their generated profile data in their own repo
• Allow deeper customization: Users can edit generated config files directly
• Support CI/CD: Profiles regenerate on a schedule or on push via GitHub Actions

Proposed Architecture

GitHub App Installation Flow

1. User clicks "Install" on profiles.sh
2. GitHub App requests permissions: read:user, read:repos, read:stars, write:contents (for the generated repo)
3. On installation, the App creates a profiles-sh repo in the user's account
4. Populates it with:
   • profile.json — computed persona data (same output as the engine)
   • .github/workflows/refresh.yml — scheduled Action to re-compute
   • config.yml — user-editable customization (featured repos, topics, etc.)
   • README.md — rendered profile card in markdown

GitHub Actions Workflow

name: Refresh Profile
on:
  schedule:
    - cron: '0 6 * * 1'  # Weekly Monday 6am
  push:
    paths: ['config.yml']
  workflow_dispatch:

The Action would:

1. Fetch user's repos, stars, orgs via GitHub API (authenticated via App token)
2. Run the persona engine (published as an npm package or bundled in the repo)
3. Write updated profile.json and README.md
4. Optionally push rendered OG image to the repo

profiles.sh Integration

When a user with the App installed visits username.profiles.sh:

1. Check if profiles-sh repo exists for the user
2. If yes, fetch profile.json from the repo (cached in R2)
3. Render from pre-computed data — no API calls needed
4. Fall back to server-side computation if repo is stale or missing

Sub-tasks

• Register GitHub App with required permissions
• Implement OAuth installation flow on profiles.sh
• Build repo scaffolding logic (create repo, populate files)
• Package persona engine for standalone use in Actions
• Create GitHub Actions workflow template
• Build config.yml schema and parser
• Add "Install App" button to profile page
• Implement repo-based profile loading on profiles.sh
• Add webhook handler for installation/uninstallation events

Dependencies

• Persona engine must be extractable as a standalone module (currently tightly coupled to Astro/CF)
• GitHub App registration requires a public URL for webhooks

Labels

enhancement, github-app, milestone:future