Curated Open Source Portfolio Template

Tip

Live Demo: You can see an example of a finished portfolio generated by this tool here: https://oss-portfolio-template.netlify.app/.

This repository is a template that automatically generates a curated portfolio of your Open Source Software (OSS) contributions. It tracks Pull Requests (PRs), issues, code reviews, co-authored commits, and collaborations, providing a detailed, organized record of your impact in the community.

The content updates automatically via a Node.js script and a GitHub Actions workflow.

---

🛠️ Quick Start Guide

1. Repository Setup

Choose how you want to start your project:

• Option A: Click Use this template at the top of this repository.

• Option B: Click Fork to create a linked copy, then clone it to your local machine:

  git clone https://github.com/adiati98/oss-portfolio-template.git

2. Environment Setup

Ensure Node.js is installed and run:

npm ci

3. Update Configuration

Open scripts/config/config.js and and update your GitHub handle.

// scripts/config/config.js

// Change this to your GitHub handle
const GITHUB_USERNAME = 'your-github-username';

4. Running Locally

To generate your files locally, you need a Personal Access Token (PAT) with public_repo scope.

1. Create .env file

   Copy the example environment file:

   cp .env.example .env

2. Add your token

   Open .env and replace your_token_here with your GitHub PAT.

3. Initialize and run the project

   Before your very first run, clear any template example data, then start the script:

   npm run clean
   npm start

3. Set up GitHub Actions (Automated Runs)

GitHub Actions remain disabled by default in repositories generated from a template.

1. Navigate to the Actions tab in your repository and click "I understand my workflows, go ahead and enable them."

2. Select the Update Contributions workflow and click Run workflow to execute the first sync manually.

3. The workflow uses the built-in GITHUB_TOKEN. Once the manual run finishes, daily and monthly schedules will take over automatically.

---

📂 Accessing Your Reports

After the script runs successfully, you can find your generated portfolio in the following locations:

• GitHub Markdown Portfolio: Navigate to contributions/markdown-generated/README.md. This is the main "front page" of your logs on GitHub. The detailed breakdowns for every three months are stored in contributions/markdown-generated/YYYY/.
• Static Website Files: If you are hosting a website, the ready-to-use HTML files are in contributions/html-generated/.

---

🌐 Publishing the Static Website (Optional)

The script generates optional HTML files for a more visual showcase.

1. All HTML files are generated in contributions/html-generated/.
2. Configure your host: Link your repository to a service like Vercel, Netlify, or GitHub Pages.
3. Set Publish Directory: Ensure your host points to the contributions/html-generated/ directory.

Note

Deployment Setup: This project automatically pushes data updates. If your hosting provider requires a manual Build Hook (like Netlify) to trigger a build, you must write and set up your specific deployment action at the bottom of the .github/workflows/update-contributions.yml file.

🎨 Customizing Colors

If you choose to host the static website, you can change the theme by updating the COLOR_PALETTE in scripts/config/constants.js. The system automatically updates backgrounds, borders, and even the favicon to match your chosen hex codes.

const COLOR_PALETTE = {
  primary: '#4338CA',    // Your main brand color
  success: '#10b981',    // Color for Open items
  merged: '#8b5cf6',     // Color for Merged items
  error: '#ef4444',      // Color for Closed items
};

---

💡 How It Works

An automation pipeline fetches, processes, and presents your GitHub activity using a Node.js script and a GitHub Actions workflow.

The Brain: The Automation Script

The script follows a clear pipeline: fetch data, process it, and generate output files.

1. Data Fetching & Processing

• GitHub API (v3): The script communicates with the GitHub REST API to collect five distinct types of community activity: Merged PRs, Issues, Reviewed PRs, Co-authored PRs, and Collaborations.
• Auto-Discovery Logic: The system automatically scans your entire contribution history to determine your "Active Since" date.
• Smart Syncing: The script performs either a fast incremental update (fetching only recent activity) or a full sync to ensure it captures every historical contribution.
• Deduplication: The script resolves the latest status for every contribution and deduplicates items that might appear in multiple search queries.
• Caching: The script maintains pr-cache.json and commit-cache.json to dramatically speed up future runs by skipping already processed pull request data and co-author commit history.

2. Output Generation (Markdown & HTML)

• Markdown Reports: The script generates detailed quarterly logs (e.g., 2024/Q1-2024.md) and a summary README.md in the contributions/markdown-generated folder. These include visual progress bars and a list of your primary focus projects.
• HTML Reports (Optional): The script generates a Tailwind-styled landing page and interactive dashboards in the contributions/html-generated folder. These serve as a professional static website.

3. Collaboration Profiles

The "All-Time Impact" dashboard automatically assigns a persona title based on your contribution data patterns. This helps viewers quickly understand your primary impact style within the open source ecosystem.

Priority	Persona Title	Focus
1	Community Mentor	Code review and technical guidance.
2	Core Contributor	Feature development and bug fixing.
3	Project Architect	Problem identification and feature planning.
4	Collaborative Partner	Pair programming and co-authoring code.
5	Ecosystem Partner	Technical discussion and community engagement.

The Automation: GitHub Action Workflow

The workflow file in the .github/workflows folder defines the automation schedule:

• Monthly Sync: A full sync that removes old caches to force a fresh verification of all historical data.
• Daily Update: A lightweight incremental run to capture activity from the last 24 hours.

The workflow uses the repository's built-in GITHUB_TOKEN for authentication and automatically commits updated reports back to your branch.