github-brag-doc

An evidence-backed brag-document generator for a GitHub account. It combines local Git history with GitHub commits, pull requests and issues, writes an auditable Markdown document, and publishes a dated version to Notion.

It never guesses business impact. Every generated contribution includes an evidence link when one is available; add customer outcomes and metrics in the Notion page's Manual notes section.

cp .env.example .env
# Edit .env with GitHub and Notion credentials.
python3 bragdoc.py run --dry-run
python3 bragdoc.py run

GITHUB_TOKEN should be a fine-grained token with read access to repository metadata, contents, pull requests and issues. It is needed for private repositories. Create a Notion integration, share the destination parent page with it, then put its secret and that page ID in .env.

python3 bragdoc.py install-schedule

This installs a macOS launchd agent for 09:00 local time every Friday. Set SCHEDULE_HOUR in .env to change the time. Logs and local artifacts live under .bragdoc/ and are intentionally ignored by Git.

• commits authored by the configured GitHub user in accessible upstream repositories;
• pull requests and issues authored by that user;
• commits from local repositories below LOCAL_REPO_ROOTS.

Run python3 bragdoc.py run --days 30 to use a different lookback period. The full evidence ledger is retained at .bragdoc/evidence.json so claims stay traceable.

• Secrets stay in .env and are never committed.
• Each Friday creates a dated child page in Notion, preserving your existing notes and previous documents.
• The tool only reads GitHub and local repositories; it writes only local artifacts, its launchd plist, and the configured Notion parent page.