status	active
type	project

Insights GitHub

Script em Python que consulta a API do GitHub e gera um snapshot com métricas dos seus repositórios: linguagem, stars, forks, views e clones dos últimos 14 dias, e a última atualização de cada um. A cada execução, compara com o snapshot anterior para calcular a variação nas últimas 24h e acumula um histórico diário em CSV.

Não roda sozinho: cada execução é manual (ou agendada externamente, ex. Task Scheduler / cron).

Estrutura

insights-github/
├── src/insights_github/
│   ├── api.py       # chamadas à API do GitHub (repos, tráfego de views/clones)
│   ├── storage.py   # cálculo de delta (24h) e persistência do histórico
│   └── cli.py       # ponto de entrada: orquestra api.py + storage.py
├── main.py          # atalho na raiz: `python main.py` chama insights_github.cli
├── data/                 # gerado localmente, não versionado (está no .gitignore)
│   ├── github_insights.csv             # snapshot mais recente (sobrescrito a cada execução)
│   └── github_historical_insights.csv  # série temporal (uma linha por repo por dia)
├── .env.example    # modelo das variáveis de ambiente necessárias
├── .env                 # credenciais reais, NÃO versionado (está no .gitignore)
├── requirements.txt
└── pyproject.toml

Pré-requisitos

• Python 3.11+
• Um personal access token do GitHub com escopo de leitura em repositórios (repo para incluir privados, ou public_repo se só quiser os públicos)

Instalação

git clone <url-do-repositorio>
cd insights-github

python -m venv .venv
.venv/Scripts/activate        # Windows
# source .venv/bin/activate   # Linux/Mac

pip install -r requirements.txt
pip install -e .

Configuração

Copie o modelo e preencha com suas credenciais:

cp .env.example .env

GITHUB_TOKEN=seu_personal_access_token
GITHUB_USER=seu_usuario_github
BASE_URL=https://api.github.com

O .env contém segredo (o token) e nunca deve ser commitado. Já está listado no .gitignore.

Uso

python main.py
# ou
python -m insights_github.cli

A cada execução, o script:

1. Busca todos os repositórios da conta (type: owner, inclui privados se o token tiver escopo)
2. Busca views e clones dos últimos 14 dias de cada um
3. Imprime um resumo no terminal
4. Atualiza data/github_insights.csv (snapshot atual) e data/github_historical_insights.csv (histórico acumulado)

Sobre as métricas

• views_14d/clones_14d: total de acessos, inclui suas próprias visitas como dono do repositório
• views_unicos/clones_unicos: visitantes únicos, melhor indicador de interesse de terceiros, já que deduplica
• delta_*_24h: variação desde a execução anterior (fica zerado até haver um snapshot anterior para comparar)

Licença

MIT. Veja LICENSE.