Important
While this tool helps document your GitHub contributions, it's crucial to remember that your impact and value to a company extends far beyond what's visible in GitHub. Many critical aspects of software engineering - such as mentoring, documentation, cross-team collaboration, and technical leadership - often happen outside of version control. For more on this topic, check out Glue Work, an excellent resource about the often-overlooked but essential work that makes teams successful.
- Install nodenv (preferred) or nvm
- Install npm or yarn package manager
- GitHub Personal Access Token (PAT) with
repoandread:orgscopes - OpenAI API key (optional, for summary and brag document generation)
- Set up your environment variables:
cp .env{.example,}- Run the setup script to configure your environment:
./script/setup- Run the tool:
./script/run --username <github-username> --lookback <months-to-look-back> --bragThis will generate three markdown files in the output directory:
- A detailed list of your GitHub contributions
- A summarized version of your contributions
- A professional brag document highlighting your achievements
- 📥 Fetches merged pull requests and closed issues from GitHub
- 🔍 Filters by author and date range (last 6 months by default)
- 📝 Generates a clean, chronological markdown document
- 🔄 Combines both PRs and issues into a single reflection document
- ⚡ Uses GitHub's official Octokit API client for efficient data retrieval
- 🤖 Optional AI-powered summary and brag document generation
- 🔒 Secure handling of API keys and sensitive data
Run the tool:
./script/run --username <github-username> --lookback <months-to-look-back> [--brag]Example:
./script/run --username bostonaholic --lookback 6 --bragRequired:
-u, --username <username>: Your GitHub username to fetch activity for-l, --lookback <number>: Number of months to look back for activity (must be a positive number)
Optional:
-p, --provider <provider>: LLM provider to use (e.g., openai, anthropic), defaults to openai-m, --model <model>: OpenAI model to use (e.g., gpt-4, gpt-3.5-turbo), defaults to gpt-4o-mini-b, --brag: Optional flag to generate a summary and brag document-i, --include-orgs <orgs...>: Only include contributions from these organizations (mutually exclusive with --exclude-orgs)-e, --exclude-orgs <orgs...>: Exclude contributions from these organizations (mutually exclusive with --include-orgs)
Basic usage:
./script/run --username bostonaholic --lookback 6 --bragChoose a model:
./script/run --username bostonaholic --lookback 6 --model gpt-3-5-turbo --bragChoose an LLM provider and model
./script/run --username bostonaholic --lookback 6 --provider anthropic --model claude-3-7-sonnet-20250219 --bragFilter by specific organizations:
./script/run --username bostonaholic --lookback 6 --include-orgs shopify githubExclude specific organizations:
./script/run --username bostonaholic --lookback 6 --exclude-orgs secret archivedRequired environment variables:
GITHUB_TOKEN: Your GitHub Personal Access Token (required)
To create a GitHub Personal Access Token:
- Go to GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic)
- Generate a new token with the following scopes:
repo(Full control of private repositories)read:org(Read organization data)
- Copy the token and add it to your
.envfile
Required for making LLM calls (one of):
OPENAI_API_KEYANTHROPIC_API_KEY
Optional for using a different provider-compatible endpoint:
OPENAI_BASE_URLANTHROPIC_BASE_URL
- API keys are only accepted through environment variables, not command-line arguments
- All file operations are sanitized to prevent path traversal attacks
- GitHub API rate limits are properly handled with informative error messages
- Input validation is performed on all user-provided parameters
- Output files are restricted to a predefined list of allowed filenames
- GitHub tokens are never logged or exposed in error messages
The script will generate one or more markdown files in the output directory:
Contains:
- A chronological list of your merged pull requests and closed issues
- Each item includes:
- Title
- Closing date
- Description/body
- Items are sorted by closing date (most recent first)
- Activity for the specified time period
Contains:
- A technical summary of your contributions
- Groups similar contributions together
- Highlights key technical changes and improvements
- Identifies patterns in the work
- Notes significant architectural changes
Contains:
- A professional brag document highlighting your achievements
- Focuses on business impact and value
- Emphasizes collaboration and leadership
- Highlights key metrics and improvements
- Suitable for performance reviews or portfolio
Note: The output directory and all generated files are automatically git-ignored to prevent accidental commits.
- If you get TypeScript errors, ensure you're using Node.js v22 or higher:
node --version-
If you get GitHub API errors:
- Verify your GitHub Personal Access Token (PAT) is correctly set in your
.envfile - Check that your PAT has the required scopes (
repoandread:org) - Ensure your PAT hasn't expired (they can be set to expire after a certain time)
- Verify you have access to the repositories you're trying to fetch data from
- Verify your GitHub Personal Access Token (PAT) is correctly set in your
-
If the script runs but generates an empty file:
- Check that you have activity in the specified time period
- Verify your GitHub username is correct
- Ensure you have the necessary permissions to access the repositories
-
If you get an error about the OpenAI API key:
- Make sure you've set it in your
.envfile - Check that the API key is valid and has sufficient credits
- Verify the .env file is in the correct location
- Make sure you've set it in your
-
If you get environment variable errors:
- Ensure your
.envfile exists and is properly formatted - Check that there are no spaces around the
=sign in your.envfile - Verify the
.envfile is in the root directory of the project
- Ensure your
- 🗞️ Hacker News
- 🐦 X