GitHub Profile & Pages Auditor
Desarrollado por / Developed by Alberto Ortiz · 🌐 albertoortiz.is-a.dev
Español
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".
Índice
- Características
- Modos de funcionamiento: con y sin API
- Requisitos previos
- Instalación
- Uso por línea de comandos
- Jerarquía de configuración
- Códigos de salida
- Formatos de salida e integración en CI
- Pruebas automatizadas
- Estructura del proyecto
- Seguridad
- Autor
- Licencia
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
.gitignorey 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) opip.
Instalación
- Sin instalar nada (recomendado), con
uv:uvx github-pages-auditor -u tu_usuario
- Instalarlo como comando:
uv tool install github-pages-auditoropip install github-pages-auditor.
El comando antiguo ver-github-pages sigue funcionando como alias.
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
# 1. Básico, sin token ni .env (modo web)
uv run github-pages-auditor -u alberto2005-coder
# 2. Con dominio personalizado y token (modo API)
uv run github-pages-auditor -u alberto2005-coder -w https://albertoortiz.is-a.dev -k ghp_tu_token
# 3. Forzar modo web aunque haya token y cambiar el archivo de salida
uv run github-pages-auditor -u alberto2005-coder -k ghp_tu_token --no-api -o mi_reporte.txt
# 4. Token por variable de entorno (más seguro: no queda en el historial del shell)
GITHUB_TOKEN=ghp_tu_token uv run github-pages-auditor -u alberto2005-coder
# 5. También funciona como módulo
python -m github_pages_auditor -u alberto2005-coder
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 o md |
No (def. txt) |
--fail-on |
Reglas que provocan código de salida 1 (o any) |
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 | |
-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
- Parámetros de consola (
-u,-w,-k,-o…). - Variables de entorno, incluidas las de un archivo
.envopcional en el directorio actual:USUARIO_GITHUB,DOMINIO_WEB,GITHUB_TOKEN,ARCHIVO_SALIDA. Un valor vacío se trata como no definido. - 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), 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 o any. Ejemplo: --fail-on missing-license,broken-pages.
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".
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 y 3.13.
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 agithub.com,raw.githubusercontent.comni a tu dominio. - Un parámetro
-kqueda en el historial del shell: es preferible la variableGITHUB_TOKEN. - No subas tu
.enva git (ya está en.gitignore). Para esta herramienta basta un token sin permisos especiales (repos públicos).
Autor
Desarrollado por Alberto Ortiz.
- GitHub: https://github.com/alberto2005-coder/
- Web personal: https://albertoortiz.is-a.dev/
Licencia
Distribuido bajo la Licencia MIT. Consulta LICENSE.
English
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, license, .gitignore and description).
It is driven entirely by command-line parameters: no .env file 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.
Table of Contents
- Features
- Operating modes: with and without API
- Prerequisites
- Installation
- Command-line usage
- Configuration precedence
- Exit codes
- Output formats and CI integration
- Automated tests
- Project structure
- Security
- Author
- License
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, license,
.gitignoreand 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) orpip.
Installation
- Without installing anything (recommended), with
uv:uvx github-pages-auditor -u your_user
- Install it as a command:
uv tool install github-pages-auditororpip install github-pages-auditor.
The old ver-github-pages command keeps working as an 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
# 1. Basic, no token and no .env (web mode)
uv run github-pages-auditor -u alberto2005-coder
# 2. Custom domain and token (API mode)
uv run github-pages-auditor -u alberto2005-coder -w https://albertoortiz.is-a.dev -k ghp_your_token
# 3. Force web mode even with a token, and change the output file
uv run github-pages-auditor -u alberto2005-coder -k ghp_your_token --no-api -o my_report.txt
# 4. Token from an environment variable (safer: not stored in shell history)
GITHUB_TOKEN=ghp_your_token uv run github-pages-auditor -u alberto2005-coder
# 5. Also works as a module
python -m github_pages_auditor -u alberto2005-coder
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 that cause exit code 1 (or any) |
No | |
--exclude-forks |
Ignore forks | No | |
--exclude-archived |
Ignore archived repositories | No | |
--inject |
Update the demos table inside a file (README) | 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 |
Colorless 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
- Command-line parameters (
-u,-w,-k,-o…). - Environment variables, including those from an optional
.envfile in the current directory:USUARIO_GITHUB,DOMINIO_WEB,GITHUB_TOKEN,ARCHIVO_SALIDA. An empty value counts as unset. - 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 analyze (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), 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 or any. Example: --fail-on missing-license,broken-pages.
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".
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 and 3.13.
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 togithub.com,raw.githubusercontent.comor your own domain. - A
-kparameter is stored in your shell history: prefer theGITHUB_TOKENenvironment 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.
- GitHub: https://github.com/alberto2005-coder/
- Personal website: https://albertoortiz.is-a.dev/
License
Distributed under the MIT License. See LICENSE.
Metadata
Release files for github-pages-auditor 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| github_pages_auditor-1.2.0.tar.gz | 30.7 kB | Without provenance | Details for github_pages_auditor-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| github_pages_auditor-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for github_pages_auditor-1.2.0-py3-none-any.whl |
Total release size: 62.2 kB
Release files / github_pages_auditor-1.2.0.tar.gz
| Download URL | github_pages_auditor-1.2.0.tar.gz |
|---|---|
| Size | 30.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6b56f65106b42c1b1d4d0a0a1b74bd1f817ca7f54bac82b67ba24163db7bf311
|
|
BLAKE2b-256 checksum How to use checksums |
594ce1eaa6f145e2ad24a9b687c323b7f91aa3d0a85c7d6352fc0800ce94947d
|
| 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.2.0-py3-none-any.whl
| Download URL | github_pages_auditor-1.2.0-py3-none-any.whl |
|---|---|
| Size | 31.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2d65571dd9858ee459deeb3279047b4bce8d9e3d0128d45b5435062e9c26966e
|
|
BLAKE2b-256 checksum How to use checksums |
146248a3f5003a5c6e04fbb85fe6c609f64e8dd797c6e95dec8bad61732a1b4f
|
| 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.2.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.