Aplicación de escritorio (macOS / Linux) construida con Tauri 2.x que sincroniza la configuración de GitHub desde un repositorio de referencia hacia uno o varios repositorios destino, con auditoría previa y deselección granular de cada cambio.
ghss resuelve un problema habitual en equipos que gestionan múltiples repositorios: mantener la configuración de GitHub consistente entre todos ellos. El flujo es:
- Conectar con tu cuenta de GitHub.
- Elegir un repo de referencia (el que tiene la configuración canónica).
- Auditar el resto de repos para ver cuáles difieren y en qué.
- Revisar los diffs con granularidad por setting antes de aplicar nada.
- Sincronizar solo lo que elijas, repo a repo, setting a setting.
El motor de diff y sync vive íntegramente en Rust (puro, sin Tauri), lo que facilita el testing y garantiza que no se aplique ningún cambio sin haberlo calculado antes.
Auth → Repos → Auditoría → Pre-sync (diff) → Ejecución
| Pantalla | Qué hace |
|---|---|
| Auth | Selecciona el método de autenticación y valida el token con GitHub. Muestra login/avatar al autenticar. |
| Repos | Lista todos los repos accesibles (personales + orgs). Marca uno como referencia (estrella) y selecciona destinos (checkbox). Repos sin permiso admin son visibles pero no seleccionables. |
| Auditoría | Compara en paralelo todos los repos listados contra la referencia. Muestra badge ✓ en sync / ✗ N diferencias por repo, expandible por categoría. Acción rápida: "seleccionar divergentes como destinos". |
| Pre-sync | Árbol Categoría → Setting, solo diferencias, formato destino → referencia. Checkbox por setting y por categoría (tri-estado). Confirmación con conteo de cambios y repos afectados. |
| Ejecución | Progreso por repo vía eventos Tauri. Errores inline sin abortar el resto. Resumen final: éxitos / warnings / errores. |
Homebrew:
brew install theburrowhub/tap/ghss
ghssActualizar: brew upgrade ghss. La fórmula instala el binario ghss, que abre la interfaz al ejecutarlo.
O descarga directa: el .dmg de la última release (Apple Silicon e Intel), ábrelo y arrastra ghss a Aplicaciones.
Descarga de la última release el .deb (Debian/Ubuntu) o el .AppImage portable:
# Debian / Ubuntu
sudo dpkg -i ghss_*_amd64.deb
# AppImage (cualquier distro)
chmod +x ghss_*.AppImage
./ghss_*.AppImageRequiere el runtime WebKitGTK (webkit2gtk-4.1), presente en la mayoría de escritorios modernos.
Documentación completa: https://theburrowhub.github.io/ghss/
- Rust toolchain stable (instalación recomendada:
rustup) - Node 20+ con npm
- Sistema operativo: macOS o Linux (Windows no soportado en v1)
ghCLI instalado y autenticado (opcional, pero es el método de auth por defecto)
# Instalar dependencias de frontend
npm install
# Arrancar en modo desarrollo (Vite HMR + Rust compilado en debug)
npm run tauri dev
# Compilar para producción (genera binario optimizado + app bundle)
npm run tauri build
# Ejecutar suite de tests Rust
cd src-tauri && cargo test
# Ejecutar suite de tests de frontend
npm testghss soporta tres métodos, seleccionables desde la pantalla de Auth:
Si tienes gh auth login ejecutado en tu máquina, ghss detecta el token automáticamente invocando gh auth token. No requiere ninguna configuración adicional.
Introduce un Personal Access Token de GitHub. ghss lo guarda de forma segura en el keychain del sistema operativo (Keychain en macOS, Secret Service en Linux via keyring). No se almacena en disco en texto plano.
El PAT necesita los scopes: repo, read:org.
Requiere registrar una OAuth App propia en GitHub y proporcionar el Client ID. ghss inicia el Device Flow, muestra el código de usuario y la URL de autorización, y sondea hasta obtener el token. Este método no requiere que gh CLI esté instalado.
Para registrar la OAuth App: GitHub → Settings → Developer settings → OAuth Apps → New OAuth App. No necesita callback URL (es Device Flow).
| Categoría | Qué incluye |
|---|---|
| Default branch | Nombre de la rama por defecto (default_branch). Si la rama no existe en el destino, se reporta "no aplicable" sin intentar crearla. |
| Features | Wiki, Issues, Projects, Discussions, Allow forking (has_wiki, has_issues, has_projects, has_discussions, allow_forking) |
| Pull Requests | Estrategias de merge (merge commit, squash, rebase), títulos y mensajes de merge commits, allow auto-merge, delete branch on merge, allow update branch |
| Others | Requerir firma en commits web (web_commit_signoff_required) |
| Tags | Rulesets con target tag (GitHub migró protected tags a rulesets) |
| Rules | Rulesets con target branch (conditions, rules, bypass_actors, enforcement) + branch protection clásica para cada rama protegida que exista en el destino |
- Upsert por nombre: si el destino tiene un ruleset con el mismo nombre →
PUT(actualizar); si no →POST(crear). - No se borran rulesets extra del destino (sync aditivo/correctivo, no destructivo).
bypass_actorscon IDs de equipos/apps de la org de referencia que no existan en el destino → se copia el ruleset sin esos actores + warning.
- Para cada rama protegida de la referencia que exista en el destino:
PUT .../protectioncon configuración completa. - Ramas que no existen en el destino → "no aplicable" + warning.
Los siguientes toggles de la UI de GitHub no se sincronizan porque GitHub no expone API pública para ellos (o se descartaron en v1). La app los identifica como "no sincronizable (sin API)":
- Sponsorships — no existe endpoint de escritura
- Restrict wiki editing to collaborators — disponible solo vía GraphQL (descartado en v1)
- Allow comments on individual commits — sin API pública
- Auto-close issues with merged linked PRs — sin API pública
- Limit branch/tag updates per push (push limits) — sin API pública
- Include Git LFS objects in archives — sin API pública
- PR creation allowed by (permisos de Pull Requests en forks) — sin API pública
Las siguientes verificaciones requieren un token válido de GitHub y no pueden ejecutarse en entornos sin acceso a api.github.com.
Prerrequisito: gh auth login con una cuenta real de GitHub.
- Abrir la app con
npm run tauri dev - En la pantalla Auth: autenticar con el método gh CLI (o PAT)
- Verificar que aparece el login/avatar del usuario
- En la pantalla Repos: confirmar que se listan repos personales y de orgs
- Marcar un repo de referencia con configuración conocida
- Ejecutar auditoría contra al menos un repo destino
- Crear un repo de prueba desechable:
gh repo create ghss-test-target --private - Ejecutar sync contra
ghss-test-targetcon algunos settings seleccionados - Verificar en GitHub web que los settings se aplicaron correctamente
- Comprobar que la pantalla de Ejecución muestra éxitos/errores correctamente
- Limpiar:
gh repo delete ghss-test-target --yes
Nota: Estos pasos están bloqueados en la verificación automatizada del proyecto porque el token de
ghCLI disponible en el entorno de CI no tiene acceso válido aapi.github.com.
ghss/
├── src-tauri/ # Backend Rust
│ ├── src/
│ │ ├── github/ # Cliente API GitHub (reqwest): repos, settings, rulesets, branch protection
│ │ ├── auth/ # gh CLI token, PAT + keyring, device flow
│ │ ├── model/ # RepoSettingsSnapshot, SettingsDiff, categorías
│ │ ├── diff/ # Motor de comparación referencia vs destino
│ │ ├── sync/ # Aplicación de cambios (PATCH repos, upsert rulesets, PUT protection)
│ │ └── commands.rs # Comandos Tauri expuestos al frontend
│ └── tests/ # Unit + integración con wiremock
└── src/ # Frontend React + TypeScript
├── views/ # Auth, Repos, Audit, PreSync, Execution
├── components/ # DiffTree, RepoList, CategoryBadge...
└── api.ts # invoke() typed wrappers
El repo lleva dos workflows de GitHub Actions:
pages.yml— despliega el sitiosite/en GitHub Pages en cada push amain. Ya activo en https://theburrowhub.github.io/ghss/release.yml— al hacer push de un tagvX.Y.Z:- Compila la app con
tauri-actionen macOS (arm64 + x86_64) y publica el.dmgen la release. - Empaqueta el binario como
ghss_<version>_<target-triple>.tar.gz(convención del tap, estilo cargo-dist comofang). - Genera/actualiza
Formula/ghss.rbentheburrowhub/homebrew-tap.
- Compila la app con
El paso 3 necesita un secret en el repo ghss:
TAP_GITHUB_TOKEN: un PAT con permiso de escritura sobretheburrowhub/homebrew-tap(mismo nombre de secret que usanfang,go-secret… en la org).
gh secret set TAP_GITHUB_TOKEN --repo theburrowhub/ghssgit tag v0.1.0
git push origin v0.1.0Nota: el
.dmgno está firmado/notarizado (requiere credenciales de Apple Developer). En macOS, la primera apertura pide confirmación en Ajustes → Privacidad y seguridad. La instalación vía Homebrew (binario) no tiene esa fricción.
- Windows
- Sync de webhooks, secrets, labels, colaboradores, environments
- Borrado de rulesets/protecciones sobrantes en repos destino
- Programación/scheduling de syncs automáticos