A GitHub Action that generates insightful visual reports from Git repositories using gitstats.

name: GitStats Report

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  gitstats:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: shenxianpeng/gitstats-action@v1
        with:
          deploy-to-pages: true

That's it. One uses line, and your report is live on GitHub Pages.

Every report ships with a badge.svg deployed right next to it — a shields.io-style badge in the gitstats brand colors showing your repository's live commit count. It updates automatically on every deploy.

Live example — this repository eats its own dog food: the gitstats.yml workflow runs this action on every push, and these badges are served from our own deployed report (click one):

After the workflow runs, open the job summary: it contains ready-to-copy badge markdown for your repository. It looks like this:

[![GitStats](https://<owner>.github.io/<repo>/badge.svg)](https://<owner>.github.io/<repo>/)

Anyone who sees the badge can click it to jump straight to your full GitStats report. The badge URL is also available programmatically via the badge_url and badge_markdown outputs.

Customizing the badge — every deploy also publishes a badges/ directory with one pre-rendered badge per metric, so a different metric is just a different URL: badges/commits.svg, badges/last-commit.svg (date of the latest commit, e.g. Aug 2026), badges/authors.svg, badges/files.svg, badges/lines.svg. Label, color, and shape are controlled through the config input:

- uses: shenxianpeng/gitstats-action@v1
  with:
    deploy-to-pages: true
    config: badge_metric=last-commit|badge_color=green|badge_style=flat-square

For full shields.io URL-parameter customization (any color, style=for-the-badge, logos), each metric is also published as badges/<metric>.json in the shields endpoint schema:

[![GitStats](https://img.shields.io/endpoint?url=https://<owner>.github.io/<repo>/badges/commits.json&style=for-the-badge)](https://<owner>.github.io/<repo>/)

- uses: shenxianpeng/gitstats-action@v1
  with:
    output: report

- uses: shenxianpeng/gitstats-action@v1
  with:
    output: report
    config: start_date=2024-01-01|end_date=2024-12-31

- uses: shenxianpeng/gitstats-action@v1
  with:
    output: report
    config: project_name=My Project|max_authors=15|exclude_exts=png,jpg,svg

- uses: shenxianpeng/gitstats-action@v1
  with:
    output: report
    ai-enabled: 'true'
    ai-provider: openai
    ai-model: gpt-4o
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

- uses: shenxianpeng/gitstats-action@v1
  with:
    output: report
    deploy-to-pages: true
    deploy-branch: my-pages-branch

If you need more control over the deployment (e.g., custom environment, deployment URL output), use the official Pages actions:

name: Deploy gitstats to pages

on:
  push:
    branches: [main]

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - uses: shenxianpeng/gitstats-action@v1
        with:
          output: gitstats-report

      - uses: actions/configure-pages@v6
      - uses: actions/upload-pages-artifact@v5
        with:
          path: gitstats-report
      - uses: actions/deploy-pages@v5
        id: deployment

Here are some commonly used gitstats configuration keys you can pass via the config input:

See the gitstats documentation for the full list.

• General: total files, lines, commits, authors, age
• Activity: commits by hour of day, day of week, month of year, year
• Authors: list of authors (commits, first/last commit date, age), author of month/year
• Files: file count by date, extensions, file churn
• Lines: line of code by date
• Tags: tags by date and author
• Badge: a shareable badge.svg with live commit count, linking readers to the report
• AI Insights (optional): natural language summaries powered by OpenAI / Claude / Gemini / Ollama

MIT — see LICENSE.