Integración domótica GitHub, gratuita y de código abierto
Sigue repositorios de GitHub: versiones, issues, estrellas, CI, escenas y widgets.
Publicado por William-De71
- Dispositivos
- Versión 0.3.0
- Requiere Gladys >=5.1.0
- ★ 0
Presentación
Sigue repositorios de GitHub desde Gladys: cada repositorio se convierte en un dispositivo con sus estrellas, forks, issues y pull requests abiertas, y su última versión, etiqueta, commit, issue, pull request y discusión. Las escenas reaccionan a una nueva versión, issue, pull request, discusión, commit, estrella o a las comprobaciones (CI) de la rama predeterminada. Tres widgets del panel muestran un repositorio, la actividad reciente y tu cuenta.
La integración consulta la API de GitHub (nube): nada más sale de tu red, y solo lee, nunca escribe en GitHub.
Requisitos
- Gladys Assistant 5.1.0 o posterior.
- Una cuenta de GitHub y un token de acceso personal. Un token de grano fino con el acceso «Public repositories» (solo lectura) basta para los repositorios públicos. Para repositorios privados, selecciónalos y concede en solo lectura «Metadata», «Contents», «Issues», «Pull requests» y «Discussions». Un token clásico sin ningún ámbito también funciona para los repositorios públicos.
Configuración
- Crea el token en github.com/settings/personal-access-tokens/new.
- Abre Integraciones → GitHub, pega el token y enumera los repositorios a seguir.
- Guarda y pulsa Probar la conexión: muestra tu cuenta, la cuota de API restante y los repositorios leídos.
| Campo | Descripción |
|---|---|
| Token de acceso personal | Obligatorio. Nunca se vuelve a mostrar ni se escribe en los registros. |
| Repositorios a seguir | propietario/nombre o el enlace de github.com, o un patrón propietario/*, separados por comas, 50 como máximo. |
| Intervalo de lectura (s) | De 60 a 3600, 120 por defecto. Es también el retardo de los disparadores de escena. |
| Idioma de los textos | Nombres de los dispositivos y resúmenes de escenas. Automático: el idioma de tu panel. |
Para seguir todos los repositorios de una cuenta u organización sin escribirlos uno a uno, escribe propietario/*, o propietario/gladys-* para los que empiezan por gladys-. Los forks y los repositorios archivados se omiten. Los patrones se combinan con nombres completos, por ejemplo prohand/gladys-*, GladysAssistant/Gladys. Por encima de 50 repositorios, los nombrados por completo van primero y después los actualizados más recientemente. La lista se vuelve a leer cada hora: un repositorio nuevo aparece en la pestaña Descubrir en menos de una hora.
Cada ronda lee los repositorios en lotes de 10, una petición por lote: con 50 repositorios a 120 segundos, la integración usa alrededor del 3 % de los 5000 puntos por hora que GitHub concede a un token.
Uso
Dispositivos
En la pestaña Descubrir, añade los repositorios y tu cuenta. Un repositorio ofrece: estrellas, forks, seguidores, issues abiertas, pull requests abiertas, pull requests fusionadas, discusiones, descargas de la última versión (si tiene archivos) y, como texto, la última versión, etiqueta, commit, issue, pull request y discusión. La cuenta ofrece seguidores, seguidos, repositorios públicos y gists públicos.
Disparadores de escena
| Disparador | Filtros | Variables |
|---|---|---|
| Versión publicada | repositorio, versión o preliminar | nombre, etiqueta, autor, enlace, resumen |
| Issue abierta | repositorio | número, título, autor, enlace, resumen |
| Pull request abierta | repositorio | número, título, autor, borrador, enlace, resumen |
| Discusión iniciada | repositorio | número, título, autor, enlace, resumen |
| Nuevo commit | repositorio | rama, SHA, mensaje, autor, enlace, resumen |
| Nueva estrella | repositorio | estrellas, estrellas añadidas, enlace, resumen |
| Comprobaciones terminadas | repositorio, superadas o fallidas | rama, SHA, mensaje, enlace, resumen |
Ejemplos:
- Cuando sale una versión de un proyecto que usas → envíate un mensaje con
{{triggerEvent.data.summary}}. - Cuando fallan las comprobaciones de tu proyecto → pon en rojo la lámpara del despacho.
- Cuando tu repositorio recibe una estrella → reproduce un sonido en el altavoz.
La primera lectura tras un arranque sirve de referencia: no se repite nada de lo ocurrido mientras Gladys estaba apagado.
Acción de escena
GitHub: leer un repositorio devuelve sus estrellas, forks, seguidores, issues y pull requests abiertas, su última versión (y su enlace), su último commit, sus comprobaciones y una frase de resumen. Un contador desconocido vale -1.
Widgets
- Repositorio de GitHub: estrellas, forks, issues, pull requests, última versión, comprobaciones de la rama predeterminada y un enlace.
- Actividad de GitHub: las últimas versiones, issues, pull requests y commits de todos los repositorios (o de uno), con filtro.
- Cuenta de GitHub: seguidores, seguidos, repositorios públicos y la cuota de API restante.
Solución de problemas
- «GitHub ha rechazado el token»: el token ha caducado o se ha revocado: crea uno nuevo.
- «No encontrado o no permitido por el token»: revisa el nombre del repositorio o da acceso al token (repositorio privado).
- «Cuota de la API de GitHub agotada»: otra herramienta usa el mismo token: aumenta el intervalo de lectura o usa un token propio. La lectura se reanuda sola.
- Sin autor de las estrellas: la integración solo recibe de GitHub el número de estrellas, no quién las ha dado.
- Para informar de un problema, abre una issue en GitHub con las versiones de Gladys y de la integración y los registros (
DEBUG=gladys-integration-sdk).
Parámetros de configuración
Estos son los parámetros que GitHub te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Acceso a GitHub | section | No | La integración lee GitHub con un token de acceso personal. Crea un token de grano fino: basta con el acceso «Public repositories», de solo lectura. Para seguir repositorios privados, selecciónalos y concede «Metadata», «Contents», «Issues», «Pull requests» y «Discussions» en solo lectura. Copia el token aquí. |
| Token de acceso personal | secret | Sí | Empieza por github_pat_ (de grano fino) o ghp_ (clásico, sin ámbito). |
| Repositorios | section | No | Cada repositorio seguido se convierte en un dispositivo en la pestaña Descubrir, junto a un dispositivo para tu cuenta. Los disparadores de escena y los widgets los eligen por dispositivo. |
| Repositorios a seguir | string | No | propietario/nombre o el enlace de github.com, separados por comas (50 como máximo). propietario/* sigue todos los repositorios de una cuenta, propietario/gladys-* los que empiezan por gladys-. |
| Intervalo de lectura (s) | number | No | Cada cuánto se lee GitHub, entre 60 y 3600 segundos. Es también el retardo de los disparadores de escena. |
| Idioma de los textos | select | No | Nombres de los dispositivos, resúmenes y salidas de las escenas. Automático: el idioma de tu panel, en cuanto se haya mostrado un widget de GitHub. |
Cómo instalar GitHub en Gladys
- En Gladys, abre Integraciones: GitHub aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/william-de71/gladys-github:0.3.0), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/William-De71/gladys-github.
GitHub requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
GitHub es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene William-De71, no el equipo principal de Gladys.
- Explorar todas las integraciones externas
- Descubrir las integraciones nativas incluidas en Gladys
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación