eliasoulkadi/shokunin/portfolio-auto

Note: last-sync.json state file is auto-created on first successful sync. Ignore "missing file" warnings on first run.

Portfolio Auto-Sync

Automatically sync GitHub repositories to your portfolio website.

Workflow

Step 1: Gather configuration

Ask the user:

• GitHub username: (default from git config)
• Portfolio type: static (projects-data.js) or supabase (API)
• Portfolio directory: Path to portfolio project
• Filters: Exclude repos (archived, forks, specific names)

Step 2: Fetch repos via GitHub API

GET /users/{username}/repos?per_page=100&sort=updated&direction=desc

Extract: name, description, html_url, homepage, language, topics, updated_at

Filter out:

• Forks (unless user opts in)
• Profile repos ({username}/{username})
• Archived repos

Step 3: Detect changes

Compare against last-sync.json (stored in skill directory).

• New repos: Not in last sync → full process
• Updated repos: updated_at changed → re-screenshot
• Unchanged repos: Skip

Step 4: Capture screenshots

For repos with a homepage or deploy URL:

const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.setViewportSize({ width: 1280, height: 800 });
await page.goto(process.env.URL, { waitUntil: 'networkidle', timeout: 15000 });
await page.screenshot({ path: `/tmp/portfolio-${name}.png`, fullPage: false });
await browser.close();

Save to portfolio's screenshot directory.

Step 5: Update portfolio data

Static (projects-data.js)

{
  title: '{repo.name}',
  description: 'Auto-generated: {description}',
  tech: '{language},{topics}',
  github_url: '{html_url}',
  live_url: '{homepage || ""}',
  featured: false
}

Supabase

const res = await fetch('https://your-site.com/api/projects', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer {token}' },
  body: JSON.stringify(projectData)
});

Step 6: Save sync state

{
  "lastSync": "2026-05-12T18:30:00Z",
  "repos": {
    "example-repo": { "updated_at": "2026-04-20T10:00:00Z", "screenshot": true }
  }
}

Step 7: Report results

Sync complete:
+ 2 new (Cyberian, Image Enhancer)
+ 1 screenshot captured
+ 1 updated (Portfolio)
- 0 errors

Notes

• Screenshots require Playwright + valid URL. Skip if no homepage.
• Never change featured: true on existing projects — only user can promote.
• Schedule via cron/GitHub Actions for weekly sync.

Error Handling

GitHub API Patterns

Repository Discovery

import requests, os
headers = {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}
# Fetch all repos (paginated)
repos = []
page = 1
while True:
    r = requests.get(f"https://api.github.com/user/repos?per_page=100&page={page}&sort=updated", headers=headers)
    batch = r.json()
    if not batch: break
    repos.extend(batch)
    page += 1
# Filter: only non-fork, non-archived, has description
candidates = [r for r in repos if not r["fork"] and not r["archived"] and r["description"]]

Rate Limiting

• GitHub API: 5,000 requests/hour (authenticated). Check X-RateLimit-Remaining header.
• For repos with 500+ repos: use conditional requests (If-None-Match with ETag)
• Sleep 1s between screenshot captures (avoid GitHub rate limit on assets)

Playwright Screenshot Pattern

from playwright.sync_api import sync_playwright
def capture(url, output_path):
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1280, "height": 800})
        page.goto(url, timeout=15000, wait_until="networkidle")
        page.screenshot(path=output_path, full_page=False)
        browser.close()

Error Recovery

• Timeout on page load -> retry once, skip if still fails (mark in output)
• Private repo -> skip (cannot screenshot without auth)
• Page crashes -> capture error state as screenshot
• DNS failure -> skip with log message

Caching Strategy

import hashlib, json, os
cache_file = ".sync-cache.json"
cache = json.load(open(cache_file)) if os.path.exists(cache_file) else {}
for repo in repos:
    key = hashlib.md5(f"{repo['full_name']}:{repo['pushed_at']}".encode()).hexdigest()
    if cache.get(repo['full_name']) == key:
        continue  # Skip: no changes since last sync
    # ... capture screenshot, update entry ...
    cache[repo['full_name']] = key
json.dump(cache, open(cache_file, 'w'))

Checklist

• [ ] GitHub token has correct scopes (repo, read:user) before fetching repos
• [ ] Screenshot runs only for repos with valid homepage URLs (HEAD check first)
• [ ] Playwright browser closed in finally block to prevent orphan processes
• [ ] Existing portfolio customizations preserved before upserting new entries
• [ ] Dry-run mode available to preview changes without executing

Sources

• GitHub REST API v3 documentation (docs.github.com/en/rest/repos/repos) — repository listing, filtering, and pagination
• Playwright documentation (playwright.dev/docs/api/class-playwright) — headless browser launch, screenshot, and viewport configuration
• Supabase JavaScript client documentation (supabase.com/docs/reference/javascript) — API insert, upsert, and auth patterns
• Node.js fs module documentation (nodejs.org/api/fs.html) — file read/write with atomic rename for sync state safety
• Personal Access Token best practices (docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — scopes, expiration, and secure storage
• GitHub Actions cron scheduling (docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) — weekly sync automation pattern
• "Automate the Boring Stuff with Python" by Al Sweigart (No Starch Press, 2nd Edition, 2019) — automation reliability patterns applicable to JavaScript automation tasks

Anti-Patterns