v0.3.10-alpha - CI Clone Formulas Validated + PyPI Install Without --pre

GitHub Traffic Tracker v0.3.10-alpha

Zero-server GitHub traffic analytics — daily collection via Actions, gist-backed storage, and a client-side dashboard. GHTraf tracks clones, views, stars, forks, and referrers beyond GitHub's 14-day API limit.

This is the first v0.3.x release published to PyPI, covering eleven versions of accumulated work since v0.2.8-alpha (Feb 28). It's also the first release installable via pip install github-traffic-tracker without the --pre flag (see #52 for the quick fix; #77 tracks the proper long-term solution).

Highlights

Empirically validated CI clone formulas — the big one (#49)

GHTraf now computes organic clones using formulas validated against 14 controlled experiments over 22 days on a dedicated private testbed repo. This is, to our knowledge, the first empirical study of how GitHub counts CI clones.

Key findings:

• 1 actions/checkout = exactly 1 clone (confirmed across all configurations)
• GITHUB_TOKEN = 1 unique cloner per UTC day regardless of run count
• PAT = separate unique identity from GITHUB_TOKEN
• Pages builds = 1 hidden clone per build (invisible to checkout-only detection — now correctly counted)
• Proportional+ceiling formula: RMSE 0.0000 with Pages detection across all 14 experiments

Read the full research: docs/ci-clone-research.md

One-time Pages backfill

On first run after upgrade, the workflow re-queries stored ciCheckouts dates (up to 31 days) for Pages builds and corrects the totals retroactively. Runs exactly once, guarded by workflowVersion < "0.3.7".

workflowVersion stamp in state.json

Every workflow run now stamps state.workflowVersion so the dashboard, future ghtraf verify (#38), and consumer repos can detect stale workflows.

GHTraf branding on dashboards

Dashboards now carry a subtle GHTraf identity:

• Header: banner image (icon + wordmark) next to "Project Statistics"
• Footer: translucent "Powered by GHTraf" circular badge (66% opacity, solid with blue glow on hover), plus text attribution with the workflow version
• Applied to both the live dashboard and the template package for ghtraf create deployments

Plan-Execute (PEV) infrastructure

ghtraf create --files-only now uses a plan-execute pattern end-to-end. The flow: plan_files() builds a Plan via scan_destination(), make_files_executor() handles copy/skip/overwrite, execute_plan() runs it with topological sort. --dry-run renders the plan without executing — PEV owns dry-run.

Supporting libraries shipped in v0.3.x:

• core_lib — shared types (Plan, Action, ActionResult, enums)
• plan_lib — executor, renderer, file ops, topological sort
• preserve_lib — manifest-tracked, hash-verified file operations (8,687 lines, ported from preservelib)
• log_lib — THAC0 verbosity system with channel diagnostics
• help_lib — CLI help rendering

THAC0 verbosity system (#30, #59)

Unified output model across all commands. CLI flags: -v, -vv, -vvv, -q, -qq, --show <channel>, --no-color. Per-channel output control with graduated quiet axis.

ghtraf create --files-only --configure fix (#75, PR #76)

The two-step workflow (ghtraf create for cloud setup → ghtraf create --files-only --configure to deploy and substitute placeholders) now works correctly. Previously, --configure was silently ignored on the --files-only path. Credit to @TheCodingDragon0 for the fix.

GitHub Actions modernization

• actions/github-script v7 → v8 (Node.js 24, fixes deprecation warnings)
• actions/upload-artifact v4 → v7
• actions/download-artifact v4 → v8

Installation

# Main package
pip install github-traffic-tracker

# Or the shorter alias (same package, different name)
pip install ghtraf

Note: Earlier 0.3.x releases published as 0.3.Xa0 PEP 440 pre-releases, which pip hides by default. Starting with v0.3.10, the package publishes as a stable-numbered version. The project remains in alpha development (see the "Alpha software" warning in the README).

Quick start

# Set up a new repo with tracking
ghtraf create --owner YOUR_USERNAME --repo YOUR_REPO

# Deploy template files to an existing repo
ghtraf create --files-only --configure

Version History (v0.3.x)

Version	Date	Key Changes
v0.3.10-alpha	2026-04-10	Current — --files-only --configure fix, PEP 440 hack, PR #76 cleanup
v0.3.9-alpha	2026-04-10	Dashboard branding tweaks, template sync fix
v0.3.8-alpha	2026-03-24	Actions deps to Node.js 24, GHTraf branding
v0.3.7-alpha	2026-03-24	CI clone formulas validated (#49), Pages detection, workflowVersion stamp
v0.3.6-alpha	2026-03-03	PEV retrofit of --files-only path
v0.3.5-alpha	2026-03-03	ghtraf init merged into ghtraf create --files-only
v0.3.4-alpha	2026-03-03	preserve_lib integration, output overrides finish (#59)
v0.3.3-alpha	2026-03-02	core_lib + plan_lib — plan-execute infrastructure (#53)
v0.3.2-alpha	2026-03-02	Unified output system — channel FDs, block text
v0.3.1-alpha	2026-03-01	ghtraf init, output bridge, domain hints
v0.3.0-alpha	2026-02-28	THAC0 verbosity system — log_lib, help_lib, CLI flags
v0.2.8-alpha	2026-02-28	PyPI publishing infrastructure and version sync

Known limitations

Documented in docs/ci-clone-research.md:

1. Custom step names on actions/checkout bypass detection (GitHub Jobs API limitation)
2. Codespaces may produce undetectable clones (untested)
3. Third-party CI using PATs appears as "organic" traffic unless they use actions/checkout
4. Pages detection relies on workflow name "pages build and deployment" being consistent

Requirements

• Python 3.10+
• GitHub CLI (gh) authenticated
• GitHub Actions enabled on target repo

Platform Support

Platform	Status
Windows 11	Tested (dogfooded)
Linux (CI)	Tested (GitHub Actions runners)
macOS	Expected to work (untested in this release)

Related Work

• tests/research/ci-clone-counting/ — the 14-experiment testbed framework
• docs/ci-clone-research.md — public research report
• Alternative: vladkens/ghstats (self-hosted Docker solution)

v0.2.8-alpha — First PyPI Release & Traffic Analytics Platform

GitHub Traffic Tracker v0.2.8-alpha

Zero-server GitHub traffic analytics — daily collection via Actions, gist-backed storage, and client-side dashboard. Tracks clones, views, stars, forks, and referrers beyond GitHub's 14-day API limit.

First release on PyPI — both github-traffic-tracker and ghtraf are now installable via pip.

Highlights

• Daily traffic collection with permanent gist-backed history beyond the 14-day API window
• Cascading recency badges — installs 1,234 (+18 24h) → (+88 wk) → (+145 mo)
• 5-tab dashboard (Overview, Installs, Views, Community, Dev) — pure client-side, no server
• ghtraf CLI with create subcommand and 138-test harness
• PyPI publishing via OIDC trusted publishers (no API tokens)

Core System

The workflow runs daily at 3am UTC via GitHub Actions, fetching clone, view, download, star, fork, and referrer data from the GitHub Traffic API. Data is merged into a running state.json in a public Gist, with Shields.io-compatible badge JSON files alongside it. Monthly snapshots go to a separate unlisted archive Gist. A static HTML dashboard reads from the Gist CDN — no backend needed.

Key data quality principles:

• Merge upward, never erase — Math.max for all monotonic traffic fields
• Delta-based dedup — tracks last-seen counts per date to only accumulate increases (fixes badge totals stuck at zero from v0.2.0)
• No false zeros — distinguishes "zero traffic" from "no data collected" for unique clones/views
• Pre-repo noise filtering — uses repoCreatedAt to filter out API backfill before the repo existed

Organic Clone Detection

CI/CD workflows inflate clone counts. GitHub Traffic Tracker separates organic clones from CI checkout noise:

• Schema v3 (v0.2.2) — per-day organic accumulation via totalOrganicClones, replacing the global subtraction formula that could produce negative values on zero-clone days
• Double-count guard (v0.2.3) — prevents first run after migration from counting today's clones twice
• Zero-traffic backfill (v0.2.5) — dates missing from the API response (meaning zero traffic) now correctly get uniqueClones: 0 instead of being omitted

Dashboard & Badges

• Cascading recency — badges show the most recent non-zero period: (+N 24h) → (+N wk) → (+N mo)
• 5-tab dashboard with Chart.js — Overview, Installs, Views, Community Trends, Dev/CI
• Community chart fix (v0.2.6) — beginAtZero: true prevents negative y-axis when all star values are 0
• Timezone projection fix (v0.2.5) — US-timezone users no longer see chart lines drop to zero between midnight UTC and the 3am workflow run
• Favicon — SVG chart icon for dashboard tab

CLI Tooling (#6)

pip install github-traffic-tracker
# or the short alias:
pip install ghtraf

The ghtraf package provides:

• ghtraf create --owner ORG --repo REPO --configure — creates badge + archive gists, sets repo variables, configures dashboard/workflow files
• Three-layer config: CLI flags > .ghtraf.json (per-project) > ~/.ghtraf/config.json (global)
• 135 unit tests + 3 e2e gist round-trip tests (pytest -m e2e)

The standalone setup-gists.py onboarding script remains available for users who don't want to install the package.

PyPI Publishing (#6)

Both package names are live on PyPI:

• github-traffic-tracker — the main package
• ghtraf — thin wrapper that depends on github-traffic-tracker (scikit-learn/sklearn pattern)

Publishing uses OIDC trusted publishers (no API tokens) via a tag-triggered GitHub Actions workflow with manual approval gate.

Templates & Onboarding

• Package-embedded templates (v0.2.6) — dashboard, README, and workflow templates shipped in src/ghtraf/templates/ with placeholder tokens for configure.py round-trip
• [GTT] gist naming (v0.2.7) — gist descriptions use [GTT] owner/repo · badges format for visual scanning and programmatic filtering
• setup-gists.py — interactive or fully-automated onboarding with --dry-run and --non-interactive modes

Version Management

sync-versions.py propagates version from version.py to src/ghtraf/_version.py and packages/ghtraf-alias/pyproject.toml with automatic PEP 440 conversion. Git hooks (pre-commit, post-commit) run it automatically.

python scripts/sync-versions.py --bump patch    # Bump and sync all files
python scripts/sync-versions.py --check         # Verify sync status
python scripts/sync-versions.py --dry-run       # Preview changes

Installation

pip install github-traffic-tracker

Requires Python 3.10+ and the gh CLI installed and authenticated.

Version History (0.x)

Version	Key Change
v0.2.8-alpha	Current — First PyPI release, version sync tooling, README alpha status
v0.2.7-alpha	Gist naming convention ([GTT] prefix), ghost gist fix
v0.2.6-alpha	Package-embedded templates, dashboard bug fixes
v0.2.5-alpha	Zero-traffic backfill, dashboard timezone fix
v0.2.4-alpha	Fix false-zero suppression of unique clones/views
v0.2.3-alpha	Organic double-count guard, mermaid fix
v0.2.2-alpha	Schema v3 organic clones, community health files
v0.2.1-alpha	Fix badge totals zero bug, README redesign
v0.2.0-alpha	ghtraf CLI package and 93-test harness
v0.1.2-alpha	Push trigger, script parameterization
v0.1.1-alpha	Setup tooling, project configuration, self-tracking
v0.1.0-alpha	Initial scaffold from NCSI Resolver + ComfyUI Triton

Platform Support

Platform	Status
Windows	Tested
Linux (Ubuntu)	Tested (GitHub Actions)
macOS	Expected to work

Requirements

• Python 3.10+
• gh CLI installed and authenticated
• GitHub repository with Actions enabled

Live Dashboards

• GitHub Traffic Tracker — This project (dogfooding since day 1)
• NCSI Resolver — Origin project
• ComfyUI Triton & SageAttention — First port