GitMetric: GitHub Portfolio Intelligence

GitMetric is a self-hosted GitHub portfolio intelligence platform that permanently archives official repository traffic data, visualises long-term performance and generates live README badges backed by your own Google Sheet.

Important

Traffic metrics are owner-only data. Use the narrowest token permissions available, restrict access to only the repositories you intend to track, and never commit credentials to the repository.

The Case Study: Why GitMetric?

1. The Problem with Standard Page-View Counters

Standard profile counters (like pixel trackers or Komarev badges) are unreliable for three major reasons:

• No Historical Context: They start tracking at exactly zero the moment you add them. If you created a repository two weeks ago and it received thousands of organic views, adding a traditional tracker today completely misses that history.
• Easily Manipulated: Every page refresh increments the count. They measure page refreshes, not genuine, authenticated user visits.
• Limited Scope: They only count visits to the main README, failing to measure codebase downloads (clones) or unique visitors.

2. The 14-Day Disappearing Act

GitHub actually tracks outstanding metrics internally (including views, unique visitors, clones, and referrers). However, GitHub discards this data after exactly 14 days.

Once that rolling window passes, older repository traffic is no longer available through GitHub's traffic API. If you do not manually write down your traffic numbers every two weeks, your project's early traction is gone forever.

Note

GitHub API Data Latency: GitHub aggregates and publishes daily traffic metrics asynchronously in backend batches. There is a standard 24 to 48-hour processing delay before a day's finalised traffic metrics are published and returned by the GitHub API. As a result, your dashboard and spreadsheet will naturally lag 1 to 2 days behind the current date. Do not worry, the data is not lost; because the daily collector fetches a rolling 14-day history, the next run will automatically backfill the missing days as soon as GitHub publishes them.

3. Understanding Algorithmic Interest

As developers, we build in public to build our reputation. But how do we know what people actually want to see?

• Which of your public repositories is actually attracting attention?
• How does a popular repository's traffic compare to one that gets no views?
• Do views spike after a LinkedIn post, a tweet, or a release?

GitMetric solves this by archiving GitHub's official daily breakdown. Instead of losing your data, GitMetric saves it to a Google Sheet daily. Over time, you build a lifetime portfolio intelligence history that proves your code is being read, cloned, and integrated.

Dashboard Previews

Portfolio Overview Dashboard

Individual Repository Details

Architecture

                       +-----------------------------+
                       |     GitHub Repositories     |
                       +--------------+--------------+
                                      | (Traffic API)
                                      v
                       +--------------+--------------+
                       |    Daily GitHub Action      | (Runs Node collector script)
                       +--------------+--------------+
                                      | (Upserts daily breakdown)
                                      v
                       +--------------+--------------+
                       |    Google Sheets Database   | (Permanent archive spreadsheet)
                       +--------------+--------------+
                                      | (Reads data on request)
                                      v
                       +--------------+--------------+
                       |      Next.js Vercel App     | (Edge-cached SVG endpoint)
                       +-------+--------------+------+
                               |              |
         (SVG Badge Render)    v              v    (HTML Dashboard)
               +---------------+--+        +--+---------------+
               |   README Badge   |        | Portfolio Panel  |
               +------------------+        +------------------+

Key Features

• Lifetime Retention: Permanently saves GitHub traffic details.
• Duplicate-Proof Upsert Engine: Checks dates and repositories in the sheet, updating existing records for the last 14 days (in case GitHub updates the counts) and appending new ones.
• Edge-Cached Badges: Badges are cached at Vercel's CDN edge for 6 hours. They load instantly in READMEs and protect your Google Sheets API from hitting rate limits.
• Premium Dark Dashboard: A custom-designed, glassmorphic analytics panel showing portfolio totals, repository lists, and copyable README badges.
• Custom SVG Charts: Pure React SVG line graphs with clean animations, grid coordinates, and zero heavy JS chart library overhead.
• Progressive Web App (PWA): Installs directly on your mobile device or desktop with offline-first caching capability and custom standalone application branding.
• Detailed Repository Intelligence: Renders real-time details for selected repositories including Top Referring Domains, Top Content Paths, Recent Commits Feed, Open Pull Requests/Issues, and tabbed grids for Stargazers, Forks, and Contributors.

Setup & Installation

Step 1: Create a Google Sheet & Service Account

1. Create a blank Google Sheet and copy the Spreadsheet ID from the URL (the characters between /d/ and /edit).
2. Go to the Google Cloud Console.
3. Create a project and search for or enable the Google Sheets API.
4. Navigate to IAM & Admin > Service Accounts and create a Service Account.
5. Click on the newly created Service Account email, go to the Keys tab, select Add Key > Create new key, and choose JSON. Save this downloaded file.
6. Share your Google Sheet with the Service Account email (e.g., github-tracker@project.iam.gserviceaccount.com) as an Editor.

Step 2: Generate a GitHub Personal Access Token (PAT)

To access traffic metrics (which are private to repository owners), the collector script needs a token with repository read scopes:

1. In GitHub, go to Settings > Developer Settings > Personal access tokens > Tokens (classic).
2. Click Generate new token (classic).
3. Select an expiration date and check the repo scope.
4. Generate the token and copy the secret (ghp_...) somewhere safe.

Step 3: Configure Repository Secrets

In your GitHub repository where you push this project code:

1. Go to Settings > Secrets and variables > Actions.
2. Click New repository secret and add the following four secrets:

Secret Name	Value
TRAFFIC_PAT_TOKEN	Your GitHub Personal Access Token (ghp_...)
GOOGLE_SERVICE_ACCOUNT_CREDENTIALS	The entire raw JSON string from your Google key file
GOOGLE_SHEETS_SPREADSHEET_ID	Your spreadsheet ID
TRACKED_REPOSITORIES	Comma-separated repositories to track (e.g., user/repo1,user/repo2)

Step 4: Deploy the Dashboard on Vercel

1. Import this repository into Vercel.
2. In the deployment settings, configure the following Environment Variables (same as above):
   • GOOGLE_SHEETS_SPREADSHEET_ID
   • GOOGLE_SERVICE_ACCOUNT_CREDENTIALS
   • TRACKED_REPOSITORIES
   • GITHUB_TOKEN (required to enable live developer tabs, referrers, and activity feeds)
   • DASHBOARD_PASSWORD (Optional: If configured, protects your dashboard with a lock screen passcode gate. Leave empty to keep it public.)
3. Deploy!

Operational Guide: Adding a New Repository

To track a new repository under your account in the future:

1. Update GitHub Secret: Go to your github-tracker repository's Settings > Secrets and variables > Actions and append the new repository (e.g., owner/new-repo) to the TRACKED_REPOSITORIES secret.
2. Trigger the Collector (Manual Backfill):
   • Go to the Actions tab of your github-tracker repository on GitHub.
   • Under Workflows, select Collect Traffic Data.
   • Click the Run workflow dropdown, keep the branch as main, and click the green Run workflow button.
   • This will immediately fetch the last 14 days of traffic history for the new repository and write it into your Google Sheet database.
3. Embed Badges: Add the badge markdown to your new project's README.md file (see the next section for query parameters).
4. View Dashboard: Open your live dashboard. The new project will automatically appear in your repository dropdown menu. No redeploys or code changes are ever required!

README Badges

Once deployed, you can embed views or clones badges directly in your READMEs.

Views Badge

![Views](https://your-domain.vercel.app/api/badge/your-repo)

Outputs: VIEWS | 1,284 (Pink badge)

Clones Badge

![Clones](https://your-domain.vercel.app/api/badge/your-repo?metric=clones)

Outputs: CLONES | 55 (Pink badge)

Query Parameters

Customise the badge using the ?metric parameter:

• ?metric=views (Default) : Total Views
• ?metric=uniques : Unique Visitors
• ?metric=clones : Total Code Clones
• ?metric=unique_clones : Unique Cloners

FAQ & Data Interpretation

Why does the dashboard show more unique visitors than the actual number of individuals?

To protect visitor privacy, GitMetric does not store cookies, IP addresses, or tracking identifiers. Since the Google Sheet database only saves anonymous daily aggregates (e.g., "1 unique view on Monday, 1 unique view on Tuesday"), the dashboard calculates totals by summing these daily uniques over time.

Therefore, if the same person (such as the repository owner) views the project on four different days, it will show as 4 unique visitors accumulated over that period rather than 1 de-duplicated individual. This is a standard trade-off for a privacy-first, cookie-less analytics platform.

Nicola Berry Principal Digital Architect nicolaberry.uk