Git Velocity

Turn your GitHub activity into a game. Track velocity. Earn achievements. Win at development.

Features • Quick Start • GitHub Action • Configuration • Achievements

---

What is Git Velocity?

Git Velocity analyzes your GitHub repositories and generates a beautiful, gamified dashboard showing developer velocity metrics. It's like Spotify Wrapped, but for your code contributions.

$ git-velocity analyze --config .git-velocity.yaml
🚀 Fetching data from GitHub...
📊 Processing 3 repositories...
🏆 Calculating scores and achievements...
✨ Generated dashboard at ./dist

$ git-velocity serve --port 8080
🌐 Starting preview server at http://localhost:8080

✨ Features

📊 Comprehensive Metrics

• Commits: Count, lines added/deleted, files changed
• Pull Requests: Opened, merged, closed, average size, time to merge
• Code Reviews: Reviews given, comments, approvals, response time
• Issues: Opened, closed, comments
• Meaningful Lines: Filter out comments, whitespace, and documentation changes from line counts

🎮 Gamification Engine

• Scoring System: Earn points for every contribution
• 115 Achievements: Tiered progression from "First Steps" to "Code Warrior"
• Leaderboards: Compete with your team
• Tier Progression: Multiple tiers per achievement category
• Activity Patterns: Track early bird, night owl, weekend commits with time-based scoring multipliers (x1 to x5)
• Streak Tracking: Daily streaks and work-week streaks (weekends don't break it!)
• General velocity chart: Visualize your velocity over time

👥 Team Analytics

• Configure teams and see aggregated metrics
• Team leaderboards and comparisons
• Member contribution breakdowns

⚡ Performance Optimized

• Local Git Analysis: Clone repos locally for 10x faster commit analysis
• Smart Caching: File-based caching with configurable TTL
• Concurrent Requests: Parallel API calls for faster data fetching
• Bot Filtering: Hardcoded patterns automatically exclude common bots (Dependabot, Renovate, GitHub Actions, etc.) with optional custom patterns

🎨 Beautiful Dashboard

• Modern Vue.js SPA with dark theme
• Responsive design for desktop and mobile
• Interactive charts and visualizations
• GitHub Pages deployment ready

🔐 Flexible Authentication

• Personal Access Token (PAT)
• GitHub App authentication
• Environment variable support

🔑 Required GitHub Token Permissions

See Token Permissions for detailed requirements.

🚀 Quick Start

Installation

# Go install
go install github.com/lukaszraczylo/git-velocity/cmd/git-velocity@latest

# Or download binary from releases
# https://github.com/lukaszraczylo/git-velocity/releases

Verifying Release Signatures

All release checksums and Docker images are signed with cosign using keyless signing. To verify:

# Verify checksum signature
cosign verify-blob \
  --certificate-identity-regexp "https://github.com/lukaszraczylo/git-velocity-analyser/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  --bundle "<checksums-file>.sigstore.json" \
  <checksums-file>

# Verify Docker image
cosign verify \
  --certificate-identity-regexp "https://github.com/lukaszraczylo/git-velocity-analyser/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  ghcr.io/lukaszraczylo/git-velocity:latest

Create Configuration

Create .git-velocity.yaml in your repository:

version: "1.0"

auth:
  github_token: "${GITHUB_TOKEN}"

repositories:
  - owner: "your-org"
    name: "your-repo"
  # Or use patterns:
  - owner: "your-org"
    pattern: "*"  # All repos in org

teams:
  - name: "Backend Team"
    members: ["dev1", "dev2", "dev3"]
    color: "#3B82F6"
  - name: "Frontend Team"
    members: ["dev4", "dev5"]
    color: "#10B981"

scoring:
  enabled: true
  points:
    commit: 10             # Base points (multiplied by time of day)
    commit_with_tests: 15
    pr_opened: 25
    pr_merged: 50
    pr_reviewed: 30
    fast_review_1h: 50
    fast_review_4h: 25
    # Time multipliers: x1 (9-5), x2 (5-9pm, 6-9am), x2.5 (9pm-12am), x5 (12-6am)

output:
  directory: "./dist"

Run Analysis

# Set your GitHub token
export GITHUB_TOKEN=ghp_your_token_here

# Run analysis
git-velocity analyze --config .git-velocity.yaml --verbose

# Preview the dashboard
git-velocity serve --port 8080

🤖 GitHub Action

Automate your velocity reports with our GitHub Action:

name: Git Velocity Report

on:
  schedule:
    - cron: '0 0 * * 1'  # Weekly on Monday
  workflow_dispatch:      # Manual trigger

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Git Velocity Analysis
        uses: lukaszraczylo/git-velocity@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          config_file: '.git-velocity.yaml'
          output_dir: './velocity-report'

      # Fix permissions - Docker container runs as root
      - name: Fix permissions
        run: sudo chown -R $USER:$USER ./velocity-report

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./velocity-report

  deploy:
    runs-on: ubuntu-latest
    needs: analyze
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Action Inputs

Input	Description	Default
github_token	GitHub token for API access	Required
config_file	Path to configuration file	.git-velocity.yaml
output_dir	Output directory for dashboard	./dist
verbose	Enable verbose output	false

Action Outputs

Output	Description
output_dir	Path to the generated dashboard

Important: The action runs as a Docker container. Note the following:

• Your config file must include the auth section with github_token: "${GITHUB_TOKEN}" - the action input does not automatically populate the config
• You must set the GITHUB_TOKEN environment variable on the action step (in addition to the github_token input)
• The "Fix permissions" step is required because the Docker container runs as root, which causes permission errors when uploading artifacts

🏆 Achievements

Git Velocity includes 115 hardcoded achievements across 26 categories with multiple progression tiers. Achievements cannot be modified via configuration to prevent manipulation.

Achievement Categories

Category	Tiers	Description
Commits	1, 10, 50, 100, 500, 1000	Track total commits made
PRs Opened	1, 10, 25, 50, 100, 250	Track pull requests created
Reviews	1, 10, 25, 50, 100, 250	Track code reviews performed
Comments	10, 50, 100, 250, 500	Track PR review comments
Lines Added	100, 1K, 5K, 10K, 50K	Track code additions
Lines Deleted	100, 500, 1K, 5K, 10K	Track code cleanup
Review Time	24h, 4h, 1h	Fast review response times
Multi-Repo	2, 5, 10	Contribution across repositories
Unique Reviewees	3, 10, 25	Reviewing different contributors
Large PRs	500, 1K, 5K lines	Big changes merged
Small PRs	5, 10, 25, 50	Atomic commits under 100 lines
Perfect PRs	1, 5, 10, 25	Merged without changes requested
Active Days	7, 30, 60, 100	Unique days with activity
Streaks	3, 7, 14, 30 days	Consecutive day contributions
Work Week Streak	3, 5, 10, 20 days	Weekday streaks (weekends don't break it!)
Early Bird	10, 25, 50, 100	Commits before 9am
Night Owl	10, 25, 50, 100	Commits after 9pm
Midnight	5, 10, 25, 50	Commits between midnight-4am
Weekend	5, 10, 25, 50	Weekend commits
Out of Hours	10, 25, 50, 100	Commits outside 9am-5pm
Documentation	100, 500, 1K, 2.5K, 5K	Comment/doc lines added
Comment Cleanup	50, 200, 500, 1K, 2.5K	Outdated comments removed
Issues Opened	1, 5, 10, 25, 50	Track issues created
Issues Closed	1, 5, 10, 25, 50	Track issues resolved
Issue Comments	5, 10, 25, 50, 100	Track issue discussion participation
Issue References	5, 10, 25, 50, 100	Track commits referencing issues

Example Achievements

Achievement	Description
🍼 First Steps	Made your first commit
👑 Code Warrior	Made 1000 commits
⚡ Speed Demon	Average review response under 1 hour
💎 Flawless	25 PRs merged without changes requested
🏢 Full Work Week	5 consecutive weekday streak
🌙 Night Owl	50 commits after 9pm
♾️ Time Bender	100 commits outside 9am-5pm
📚 Documentation Hero	Added 1000 lines of comments/docs
🏛️ Code Historian	Added 5000 lines of comments/docs
✂️ Comment Trimmer	Removed 50 outdated comment lines
💀 Dead Code Hunter	Removed 500 outdated comment lines
🎫 Issue Opener	Opened your first issue
🏷️ Issue Tracker	Opened 25 issues
✅ Issue Closer	Closed your first issue
🔗 Issue Linker	25 commits referencing issues

🔑 GitHub Token Permissions

Git Velocity requires specific GitHub API permissions to fetch repository data. Below are the required permissions for each authentication method.

Personal Access Token (Classic)

When creating a classic Personal Access Token, select the following scopes:

Scope	Required	Description
repo	✅ Yes	Full access to private repositories (includes commits, PRs, issues)
read:org	⚠️ If using org patterns	Required when using pattern: "*" to list organization repositories

Note: For public repositories only, the public_repo scope is sufficient instead of full repo access.

Fine-Grained Personal Access Token (Recommended)

Fine-grained tokens provide more granular control. Configure the following permissions:

Repository Permissions:

Permission	Access Level	Description
Contents	Read	Access commit data and file contents
Pull requests	Read	Access PR data, reviews, and comments
Issues	Read	Access issue data and comments
Metadata	Read	Basic repository information (automatically included)

Account Permissions:

Permission	Access Level	Description
Email addresses	Read	Access public email for user deduplication

GitHub App Authentication

When using GitHub App authentication, configure the following permissions:

Repository Permissions:

Permission	Access Level	Description
Contents	Read	Fetch commits and diffs
Pull requests	Read	Fetch PRs, reviews, and review comments
Issues	Read	Fetch issues and issue comments
Metadata	Read	Repository metadata (required)

Organization Permissions (if using org patterns):

Permission	Access Level	Description
Members	Read	List organization repositories

Account Permissions:

Permission	Access Level	Description
Email addresses	Read	User profile deduplication

GitHub Actions (GITHUB_TOKEN)

When running in GitHub Actions, the default GITHUB_TOKEN has sufficient permissions for repositories in the same organization/account. For cross-organization access, use a PAT or GitHub App.

API Endpoints Used

Git Velocity uses the following GitHub REST API endpoints:

Endpoint	Purpose
GET /orgs/{org}/repos	List repositories by organization
GET /repos/{owner}/{repo}/commits	Fetch commit history
GET /repos/{owner}/{repo}/commits/{sha}	Fetch commit details with diff
GET /repos/{owner}/{repo}/pulls	List pull requests
GET /repos/{owner}/{repo}/pulls/{number}/reviews	Fetch PR reviews
GET /repos/{owner}/{repo}/issues	List issues
GET /users/{username}	Fetch user profile information

⚙️ Configuration

Full Configuration Reference

version: "1.0"

auth:
  # Option 1: Personal Access Token
  github_token: "${GITHUB_TOKEN}"

  # Option 2: GitHub App
  github_app:
    app_id: 123456
    installation_id: 789012
    private_key_path: "./private-key.pem"

repositories:
  # Single repository
  - owner: "your-org"
    name: "repo-name"
  # All repos in organization
  - owner: "your-org"
    pattern: "*"
  # Pattern matching
  - owner: "your-org"
    pattern: "frontend-*"

date_range:
  start: "2024-01-01"
  end: "2024-12-31"

teams:
  - name: "Backend Team"
    members: ["user1", "user2"]
    color: "#3B82F6"

scoring:
  enabled: true
  points:
    commit: 10
    commit_with_tests: 15
    # Line scoring always uses meaningful lines (excludes comments/whitespace)
    lines_added: 0.1
    lines_deleted: 0.05
    pr_opened: 25
    pr_merged: 50
    pr_reviewed: 30
    review_comment: 5
    issue_opened: 10
    issue_closed: 20
    issue_comment: 5
    issue_reference_commit: 5
    fast_review_1h: 50
    fast_review_4h: 25
    fast_review_24h: 10
    # Time-based commit multipliers (applied to base commit points)
    multiplier_regular_hours: 1.0   # 9am-5pm
    multiplier_evening: 2.0         # 5pm-9pm
    multiplier_late_night: 2.5      # 9pm-midnight
    multiplier_overnight: 5.0       # midnight-6am
    multiplier_early_morning: 2.0   # 6am-9am

output:
  directory: "./dist"
  format: ["html", "json"]
  deploy:
    gh_pages: true
    artifact: true

cache:
  enabled: true
  directory: "./.cache"
  ttl: "24h"

options:
  concurrent_requests: 5
  include_bots: false
  # Add custom bot patterns (hardcoded defaults always apply)
  additional_bot_patterns:
    - "my-org-bot"
    - "jenkins*"
  clone_directory: "./.repos"
  user_aliases:
    - github_login: "username"
      emails: ["work@example.com", "personal@example.com"]
      names: ["Full Name", "nickname"]

User Aliases

Map multiple git emails/names to a single GitHub login:

options:
  user_aliases:
    - github_login: "johndoe"
      emails:
        - "john.doe@company.com"
        - "johnd@personal.com"
      names:
        - "John Doe"
        - "JD"

Bot Filtering

Bot filtering uses hardcoded default patterns that always apply when include_bots: false. These cannot be disabled to ensure consistent filtering:

Default Bot Patterns (always applied):

• *[bot] - GitHub App bots (dependabot[bot], renovate[bot], etc.)
• dependabot* - Dependabot variants
• renovate* - Renovate bot variants
• github-actions* - GitHub Actions
• codecov* - Codecov bot
• snyk* - Snyk security bot
• greenkeeper* - Greenkeeper (legacy)
• imgbot* - Image optimization bot
• allcontributors* - All Contributors bot
• semantic-release* - Semantic release bot

Add custom patterns for your organization's bots:

options:
  include_bots: false  # When false, hardcoded + additional patterns apply
  additional_bot_patterns:
    - "my-org-bot"     # Exact match
    - "jenkins*"       # Prefix match
    - "*-ci"           # Suffix match

Meaningful Lines Filtering

Git Velocity always filters out non-meaningful code changes when scoring line additions and deletions. This provides an accurate measure of actual code contributions.

What's filtered out:

• Comments: Single-line (//, #, --), block (/* */, <!-- -->), docstrings (""", ''')
• Whitespace: Empty lines, whitespace-only lines
• Documentation files: .md, .rst, .txt, README, CHANGELOG, LICENSE, files in docs/ directories

Supported comment styles:

• C-style: //, /* */, * (block continuation)
• Python/Shell: #, """, '''
• SQL/Lua/Haskell: --
• Assembly/Lisp/INI: ;
• VB: '
• HTML/XML: <!-- -->

Environment Variables

All configuration values support environment variable expansion:

auth:
  github_token: "${GITHUB_TOKEN}"
  github_app:
    private_key: "${GITHUB_APP_PRIVATE_KEY}"

📖 CLI Commands

analyze

Analyze repositories and generate the dashboard.

git-velocity analyze [flags]

Flags:
  -c, --config string   Path to configuration file (default "config.yaml")
  -o, --output string   Output directory for generated site (default "./dist")
  -v, --verbose         Enable verbose output

serve

Start a local preview server.

git-velocity serve [flags]

Flags:
  -d, --directory string   Directory to serve (default "./dist")
  -p, --port string        Port to listen on (default "8080")

version

Print version information.

git-velocity version

🛠️ Development

# Clone repository
git clone https://github.com/lukaszraczylo/git-velocity.git
cd git-velocity

# Install dependencies
go mod download
cd web && npm install && cd ..

# Build
make build

# Run tests
make test

# Build SPA
make build-spa

📄 License

MIT License - see LICENSE for details.

🙏 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Made with ❤️ by Lukasz Raczylo

⭐ Star this repo if you find it useful!