Skip to main content

GitHub Profile & Pages Auditor

Python PyPI CI MIT

Español · English

Desarrollado por Alberto Ortiz · albertoortiz.is-a.dev


Español

Índice

Descripción

Herramienta de línea de comandos en Python para auditar los repositorios públicos de un usuario de GitHub: mapea los enlaces de GitHub Pages (incluido un dominio personalizado), detecta releases y evalúa la calidad del repositorio (README, licencia, .gitignore y descripción).

Se controla solo con parámetros de consola: no necesita archivo .env. El token de la API es opcional: con token usa la API oficial de GitHub; sin token usa un modo web público de «mejor esfuerzo».

Características

  • Mapeo de GitHub Pages: raíz (<usuario>.github.io) o subruta por repositorio, verificando que la URL responde de verdad.
  • Releases: detectadas mediante el feed Atom público, sin consumir cuota de la API.
  • Auditoría de calidad: sin README, sin licencia, sin .gitignore y sin descripción (About).
  • Clasificación: forks y repositorios archivados.
  • Rendimiento: todo el análisis se hace en paralelo (ThreadPoolExecutor) con reintentos y timeout.
  • Informe determinista: los repositorios salen siempre en el mismo orden; un fallo de red en un repo no tumba el resto (se lista aparte).
  • Créditos del autor en --help, --version, la consola y el informe.

Modos de funcionamiento: con y sin API

Con token (-k / GITHUB_TOKEN) Sin token
Fuente de datos API REST oficial (5.000 peticiones/hora) Páginas públicas de GitHub (HTML, raw, Atom)
Fiabilidad Alta De mejor esfuerzo: depende del marcado público de GitHub
Límite 5.000/h Puede recibir 429 si se abusa
Se activa Automáticamente si hay token Si no hay token, o con --no-api

El token solo se envía a api.github.com.

URL de las Pages: con API se usa la URL real que GitHub tiene configurada (incluido tu dominio personalizado). Sin API, si no indicas -w, se prueba https://<usuario>.github.io/... y, si GitHub redirige a tu dominio personalizado, se detecta y se muestra ese dominio. Con -w se comprueba directamente ese dominio.

Requisitos previos

  • Python 3.10 o superior.
  • Gestor de paquetes: uv (recomendado) o pip.

Instalación

  • Sin instalar nada (recomendado), con uv:

    uvx github-pages-auditor -u tu_usuario
    
  • Instalarlo globalmente como comando:

    uv tool install github-pages-auditor
    # o mediante pip:
    pip install github-pages-auditor
    

El comando antiguo ver-github-pages sigue funcionando como alias de compatibilidad.

Para desarrollar desde el código fuente:

git clone https://github.com/alberto2005-coder/github-pages-auditor.git
cd github-pages-auditor
  • Con uv (recomendado):

    uv sync
    
  • Con pip:

    pip install -e .
    

Uso por línea de comandos

github-pages-auditor -u USUARIO [-w DOMINIO] [-k TOKEN] [-o ARCHIVO] [opciones]

Ejemplos (si ejecutas desde el repositorio sin instalar globalmente, antepón uv run)

# 1. Básico, sin token ni .env (modo web)
github-pages-auditor -u alberto2005-coder

# 2. Con dominio personalizado y token por variable de entorno (modo API; recomendado)
export GITHUB_TOKEN=github_pat_xxx        # PowerShell: $env:GITHUB_TOKEN = "github_pat_xxx"
github-pages-auditor -u alberto2005-coder -w https://albertoortiz.is-a.dev

# 3. Forzar modo web aunque haya token en el entorno y cambiar el archivo de salida
github-pages-auditor -u alberto2005-coder --no-api -o mi_reporte.txt

# 4. Token como parámetro (funciona, pero queda en el historial del shell)
github-pages-auditor -u alberto2005-coder -k github_pat_xxx

# 5. También funciona como módulo de Python (útil si Scripts no está en el PATH)
python -m github_pages_auditor -u alberto2005-coder

Un token fine-grained sin permisos (solo repositorios públicos) es suficiente.

Opciones

Parámetro Alternativas Descripción Obligatorio
-u --usuario, --user Usuario de GitHub Sí (o USUARIO_GITHUB)
-w --web, --dominio Dominio base de las Pages No (def. https://<usuario>.github.io)
-k --key, --token Personal Access Token (activa la API) No
-o --output Archivo del informe; - = salida estándar No (def. paginas_github.<formato>)
-f --format txt, json, md o github (anotaciones de Actions) No (def. txt)
--fail-on Reglas (o grupos any, community, all) que provocan código de salida 1 No
--exclude-forks Ignora los forks No
--exclude-archived Ignora los repositorios archivados No
--inject Actualiza la tabla de demos dentro de un archivo (README) No
--ignore Excluye repos por nombre o patrón (a,b*) No
--only Audita solo estos repos (nombres o patrones) No
--details Estrellas, lenguaje, licencia, último push y release No
--sort listing (def.), name, stars, updated No
--stale-months Meses sin push para stale-repo No (def. 12)
--baseline Informe JSON previo: --fail-on solo por hallazgos nuevos No
--config Archivo TOML de configuración No (def. .github-pages-auditor.toml)
--no-config No leer el archivo de configuración No
-q --quiet Sin tablas ni progreso No
--workers Hilos en paralelo No (def. 15)
--timeout Timeout por petición, en segundos No (def. 10)
--no-api Fuerza el modo web aunque haya token No
--no-color Consola sin colores No
--no-env No leer el archivo .env No
-V --version Versión y créditos No
-h --help Ayuda y créditos No

Jerarquía de configuración

  1. Parámetros de consola (-u, -w, -k, -o…).
  2. Variables de entorno, incluidas las de un archivo .env opcional en el directorio actual: USUARIO_GITHUB, DOMINIO_WEB, GITHUB_TOKEN, ARCHIVO_SALIDA. Un valor vacío se trata como no definido.
  3. Archivo .github-pages-auditor.toml (opcional, en el directorio actual): claves user, web, output, format, fail_on, exclude_forks, exclude_archived, ignore, only, stale_months, workers, timeout, details, sort, no_api, quiet, no_color, baseline. No admite el token (es un error ponerlo ahí). --no-config lo ignora.
  4. Valores por defecto.

Hay una plantilla en .env.example.

Códigos de salida

Código Significado
0 Auditoría correcta e informe escrito
1 Una regla de --fail-on encontró hallazgos (el informe sí se escribe)
2 Error: parámetros inválidos, usuario inexistente, token rechazado, límite de tasa, red o escritura
3 No hay repositorios que analizar (no se escribe informe)
130 Cancelado con Ctrl+C

Formatos de salida e integración en CI

-f/--format elige el formato del informe: txt (por defecto), json o md. Con -o - el informe va a la salida estándar y la interfaz a stderr, así que se puede encadenar con otras herramientas:

uvx github-pages-auditor -u alberto2005-coder -f json -o - -q | jq '.summary'

JSON (schema_version: 1): tool, generated_at, user, mode (api/web), domain, summary (contadores), findings (una lista por regla, vacía si no hay hallazgos), fail_on (reglas pedidas y disparadas) y repos (un objeto por repositorio, con pages.status, pages.problems, pages.warnings, pages.title, etc.).

Markdown (-f md): tabla de tus demos en vivo, ordenada y sin forks, entre los marcadores <!-- github-pages-auditor:start --> y <!-- github-pages-auditor:end -->. Con --inject README.md se actualiza dentro de ese archivo, entre esos marcadores (si no existen, falla sin tocar nada).

Reglas de --fail-on: missing-readme, missing-license, missing-gitignore, missing-description, broken-pages, analysis-errors (any = estas), más las de comunidad (solo modo API; no aplican a forks ni archivados): missing-security-policy, missing-contributing, missing-code-of-conduct, missing-issue-template, missing-topics, missing-homepage, stale-repo (community = estas; all = todas). Ejemplo: --fail-on missing-license,broken-pages.

-f github escribe anotaciones ::error::/::warning:: para el log de Actions; --baseline informe.json compara con un informe anterior y --fail-on solo se dispara por hallazgos nuevos. Action reutilizable: uses: alberto2005-coder/github-pages-auditor@v1.3.0 (ver docs/ci.md).

Salud de Pages. Para cada sitio se comprueba, además del código 200: errores TLS, timeouts, redirecciones a otro dominio o en bucle, página vacía o sin HTML, y lentitud (aviso). Con token se sabe qué repos tienen Pages activadas, así que un 404, un build fallido (errored) o cualquier fallo cuenta como Pages rotas. Sin token no se puede saber si un repo debería tener Pages, por lo que un fallo solo significa «no hay Pages».

Contrato completo del JSON: docs/json-schema.md. Más recetas de CI (resumen del job, refresco semanal del README): docs/ci.md.

Ejemplo de CI (GitHub Actions):

- run: uvx github-pages-auditor -u ${{ github.repository_owner }} -k ${{ secrets.GITHUB_TOKEN }} -f json -o report.json --fail-on missing-license,broken-pages

Pruebas automatizadas

Los tests usan una sesión HTTP falsa: no tocan la red ni consumen cuota de GitHub.

uv run pytest          # o: pip install -r requirements-dev.txt && pytest

Cubren configuración y prioridades, cliente HTTP, ambos proveedores (API y web), orquestación en paralelo, informe, CLI, códigos de salida y créditos. La integración continua (GitHub Actions) los ejecuta en Linux, macOS y Windows con Python 3.10, 3.13 y 3.14.

Estructura del proyecto

github-pages-auditor/
├── .github/workflows/test.yml    # Integración continua
├── .github/workflows/publish.yml # Publicación en PyPI
├── .env.example                  # Plantilla opcional de variables
├── .gitignore
├── CHANGELOG.md                  # Historial de versiones
├── LICENSE
├── README.md
├── pyproject.toml
├── requirements.txt              # Dependencias para pip
├── requirements-dev.txt          # + pytest
├── uv.lock
├── src/github_pages_auditor/
│   ├── __init__.py               # Versión y créditos del autor
│   ├── __main__.py               # python -m github_pages_auditor
│   ├── main.py                   # Punto de entrada de la CLI
│   ├── config.py                 # Argumentos y entorno
│   ├── audit.py                  # Orquestación en paralelo
│   ├── github_api.py             # Proveedor: API oficial (con token)
│   ├── github_web.py             # Proveedor: web pública (sin token)
│   ├── http.py                   # Sesión con reintentos y timeout
│   ├── pages.py                  # URLs de GitHub Pages
│   ├── pages_health.py           # Salud de Pages (404, TLS, redirecciones...)
│   ├── rules.py                  # Reglas de --fail-on
│   ├── formatters.py             # Salidas JSON y Markdown
│   ├── models.py                 # Estructuras de datos
│   ├── errors.py                 # Excepciones propias
│   └── report.py                 # Consola (Rich) e informe .txt
└── tests/                        # Suite de pytest

Seguridad

  • El token se envía únicamente a api.github.com, nunca a github.com, raw.githubusercontent.com ni a tu dominio.
  • Un parámetro -k queda en el historial del shell: es preferible la variable GITHUB_TOKEN.
  • No subas tu .env a git (ya está en .gitignore). Para esta herramienta basta un token sin permisos especiales (repos públicos).

Autor

Desarrollado por Alberto Ortiz.

Licencia

Distribuido bajo la Licencia MIT. Consulta LICENSE. © 2026 Alberto Ortiz.


English

Table of contents

Overview

A Python command-line tool that audits a GitHub user's public repositories: it maps GitHub Pages links (including a custom domain), detects releases, and checks repository quality (README, licence, .gitignore and description).

It is driven entirely by command-line parameters: no .env file is needed. The API token is optional: with a token it uses the official GitHub API; without one it falls back to a best-effort public web mode.

Features

  • GitHub Pages mapping: root (<user>.github.io) or per-repository subpath, verifying that the URL really responds.
  • Releases: detected through the public Atom feed, without using API quota.
  • Quality audit: missing README, licence, .gitignore and description (About).
  • Classification: forks and archived repositories.
  • Performance: all checks run in parallel (ThreadPoolExecutor) with retries and timeouts.
  • Deterministic report: repositories always appear in the same order; a network failure on one repo does not abort the rest (it is listed separately).
  • Author credits in --help, --version, the console and the report.

Operating modes: with and without API

With token (-k / GITHUB_TOKEN) Without token
Data source Official REST API (5,000 requests/hour) Public GitHub pages (HTML, raw, Atom)
Reliability High Best effort: depends on GitHub's public markup
Limit 5,000/h May receive 429 if abused
Enabled Automatically when a token is present When no token is given, or with --no-api

The token is only ever sent to api.github.com.

Pages URL: with the API, the real URL configured on GitHub is used (including your custom domain). Without the API and without -w, https://<user>.github.io/... is tried and, if GitHub redirects to your custom domain, that domain is detected and shown. With -w, that domain is checked directly.

Prerequisites

  • Python 3.10 or higher.
  • Package manager: uv (recommended) or pip.

Installation

  • Without installing anything (recommended), with uv:

    uvx github-pages-auditor -u your_user
    
  • Install it globally as a command:

    uv tool install github-pages-auditor
    # or via pip:
    pip install github-pages-auditor
    

The old ver-github-pages command keeps working as a compatibility alias.

To work from source:

git clone https://github.com/alberto2005-coder/github-pages-auditor.git
cd github-pages-auditor
  • Using uv (recommended):

    uv sync
    
  • Using pip:

    pip install -e .
    

Command-line usage

github-pages-auditor -u USER [-w DOMAIN] [-k TOKEN] [-o FILE] [options]

Examples (if running from source without a global install, prefix with uv run)

# 1. Basic, no token and no .env (web mode)
github-pages-auditor -u alberto2005-coder

# 2. Custom domain and token from an environment variable (API mode; recommended)
export GITHUB_TOKEN=github_pat_xxx        # PowerShell: $env:GITHUB_TOKEN = "github_pat_xxx"
github-pages-auditor -u alberto2005-coder -w https://albertoortiz.is-a.dev

# 3. Force web mode even with a token in the environment, and change the output file
github-pages-auditor -u alberto2005-coder --no-api -o my_report.txt

# 4. Token as a parameter (works, but it stays in your shell history)
github-pages-auditor -u alberto2005-coder -k github_pat_xxx

# 5. Also works as a Python module (useful if Scripts is not on PATH)
python -m github_pages_auditor -u alberto2005-coder

A fine-grained token with no permissions (public repositories only) is enough.

Options

Flag Aliases Description Required
-u --usuario, --user GitHub username Yes (or USUARIO_GITHUB)
-w --web, --dominio Base domain of the Pages site No (default https://<user>.github.io)
-k --key, --token Personal Access Token (enables the API) No
-o --output Report file; - = standard output No (default paginas_github.<format>)
-f --format txt, json or md No (default txt)
--fail-on Rules (or groups any, community, all) that cause exit code 1 No
--exclude-forks Ignore forks No
--exclude-archived Ignore archived repositories No
--inject Update the demos table inside a file (README) No
--ignore Exclude repos by name or pattern (a,b*) No
--only Audit only these repos (names or patterns) No
--details Stars, language, license, last push and release No
--sort listing (default), name, stars, updated No
--stale-months Months without a push for stale-repo No (default 12)
--baseline Previous JSON report: --fail-on only for NEW findings No
--config TOML configuration file No (default .github-pages-auditor.toml)
--no-config Do not read the configuration file No
-q --quiet No tables or progress No
--workers Parallel threads No (default 15)
--timeout Per-request timeout, in seconds No (default 10)
--no-api Force web mode even with a token No
--no-color Colourless console output No
--no-env Do not read the .env file No
-V --version Version and credits No
-h --help Help and credits No

Configuration precedence

  1. Command-line parameters (-u, -w, -k, -o…).
  2. Environment variables, including those from an optional .env file in the current directory: USUARIO_GITHUB, DOMINIO_WEB, GITHUB_TOKEN, ARCHIVO_SALIDA. An empty value counts as unset.
  3. Built-in defaults.

A template is provided in .env.example.

Exit codes

Code Meaning
0 Audit succeeded and report written
1 A --fail-on rule found issues (the report is still written)
2 Error: invalid parameters, unknown user, rejected token, rate limit, network or write failure
3 No repositories to analyse (no report is written)
130 Cancelled with Ctrl+C

Output formats and CI integration

-f/--format selects the report format: txt (default), json or md. With -o - the report goes to standard output and the UI to stderr, so it can be piped:

uvx github-pages-auditor -u alberto2005-coder -f json -o - -q | jq '.summary'

JSON (schema_version: 1): tool, generated_at, user, mode (api/web), domain, summary (counters), findings (one list per rule, empty when clean), fail_on (requested and triggered rules) and repos (one object per repository, with pages.status, pages.problems, pages.warnings, pages.title, etc.).

Markdown (-f md): a sorted table of your live demos, forks excluded, between the <!-- github-pages-auditor:start --> and <!-- github-pages-auditor:end --> markers. --inject README.md updates it inside that file, between those markers (if they are missing it fails without touching anything).

--fail-on rules: missing-readme, missing-license, missing-gitignore, missing-description, broken-pages, analysis-errors (any = these), plus community rules (API mode only; not applied to forks or archived repos): missing-security-policy, missing-contributing, missing-code-of-conduct, missing-issue-template, missing-topics, missing-homepage, stale-repo (community = these; all = everything). Example: --fail-on missing-license,broken-pages.

-f github writes ::error::/::warning:: annotations for the Actions log; --baseline report.json compares with a previous report so --fail-on only triggers on NEW findings. Reusable Action: uses: alberto2005-coder/github-pages-auditor@v1.3.0 (see docs/ci.md).

Pages health. Besides a 200 status, each site is checked for TLS errors, timeouts, redirects to another domain or loops, empty or non-HTML pages, and slowness (warning). With a token the tool knows which repos have Pages enabled, so a 404, a failed build (errored) or any failure counts as broken Pages. Without a token it cannot know whether a repo should have Pages, so a failure just means “no Pages”.

Full JSON contract: docs/json-schema.md. More CI recipes (job summary, weekly README refresh): docs/ci.md.

CI example (GitHub Actions):

- run: uvx github-pages-auditor -u ${{ github.repository_owner }} -k ${{ secrets.GITHUB_TOKEN }} -f json -o report.json --fail-on missing-license,broken-pages

Automated tests

Tests use a fake HTTP session: they never touch the network or use GitHub quota.

uv run pytest          # or: pip install -r requirements-dev.txt && pytest

They cover configuration and precedence, the HTTP client, both providers (API and web), parallel orchestration, the report, the CLI, exit codes and credits. Continuous integration (GitHub Actions) runs them on Linux, macOS and Windows with Python 3.10, 3.13 and 3.14.

Project structure

github-pages-auditor/
├── .github/workflows/test.yml    # Continuous integration
├── .github/workflows/publish.yml # PyPI publishing
├── .env.example                  # Optional variables template
├── .gitignore
├── CHANGELOG.md                  # Version history
├── LICENSE
├── README.md
├── pyproject.toml
├── requirements.txt              # pip dependencies
├── requirements-dev.txt          # + pytest
├── uv.lock
├── src/github_pages_auditor/
│   ├── __init__.py               # Version and author credits
│   ├── __main__.py               # python -m github_pages_auditor
│   ├── main.py                   # CLI entry point
│   ├── config.py                 # Arguments and environment
│   ├── audit.py                  # Parallel orchestration
│   ├── github_api.py             # Provider: official API (with token)
│   ├── github_web.py             # Provider: public web (no token)
│   ├── http.py                   # Session with retries and timeout
│   ├── pages.py                  # GitHub Pages URLs
│   ├── pages_health.py           # Pages health (404, TLS, redirects...)
│   ├── rules.py                  # --fail-on rules
│   ├── formatters.py             # JSON and Markdown output
│   ├── models.py                 # Data structures
│   ├── errors.py                 # Custom exceptions
│   └── report.py                 # Console (Rich) and .txt report
└── tests/                        # pytest suite

Security

  • The token is sent only to api.github.com, never to github.com, raw.githubusercontent.com or your own domain.
  • A -k parameter is stored in your shell history: prefer the GITHUB_TOKEN environment variable.
  • Do not commit your .env (it is already in .gitignore). A token with no special scopes (public repos) is enough for this tool.

Author

Developed by Alberto Ortiz.

License

Distributed under the MIT License. See LICENSE. © 2026 Alberto Ortiz.

Metadata

Release files for github-pages-auditor 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for github-pages-auditor 1.3.0
File Size Uploaded Provenance Actions
github_pages_auditor-1.3.0.tar.gz 40.6 kB Without provenance Details for github_pages_auditor-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for github-pages-auditor 1.3.0
File Interpreter ABI Platform Actions
github_pages_auditor-1.3.0-py3-none-any.whl Python 3 none any Details for github_pages_auditor-1.3.0-py3-none-any.whl

Total release size: 82.2 kB

Release files / github_pages_auditor-1.3.0.tar.gz

Download URL github_pages_auditor-1.3.0.tar.gz
Size 40.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d0e849368fd2e3e530c49ce8092905fb799c20986f9e6423f59ea0cd423c1107
BLAKE2b-256 checksum
How to use checksums
799661c39345210ab4d1f48beb75895421eea82e7b1572e1225ba29ecc5a52ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / github_pages_auditor-1.3.0-py3-none-any.whl

Download URL github_pages_auditor-1.3.0-py3-none-any.whl
Size 41.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
366ec7e6a9fadd5ac055f4aa5a046f29700de23dbe4646486702e7e7926f87a1
BLAKE2b-256 checksum
How to use checksums
bae128361ab81354675be3401e90578eb37f8466c9eece66267e1ca114561792
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for github-pages-auditor 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page