Je vous présente une intégration externe pour suivre vos dépôts GitHub depuis Gladys.
Ce qu’elle fait
Chaque dépôt suivi devient un appareil dans Gladys, et votre compte aussi. L’intégration s’inspire de l’intégration GitHub de Home Assistant et y ajoute des déclencheurs de scène et des widgets. Elle passe par l’API de GitHub (cloud) avec un jeton d’accès personnel en lecture seule : elle ne contacte rien d’autre et n’écrit jamais sur GitHub. Elle sert à ceux qui publient du code ou qui veulent être prévenus des nouvelles versions d’un projet qu’ils utilisent.
Fonctionnalités
Appareil par dépôt : étoiles, forks, abonnés, issues et pull requests ouvertes, pull requests fusionnées, discussions, téléchargements de la dernière version, et en texte la dernière version, le dernier tag, commit, issue, pull request et discussion.
Appareil du compte : abonnés, abonnements, dépôts et gists publics.
7 déclencheurs de scène : version publiée (filtre version / préversion), issue ouverte, pull request ouverte, discussion lancée, nouveau commit, nouvelle étoile, vérifications (CI) réussies ou en échec.
1 action de scène : lire les chiffres d’un dépôt (pour un message ou une condition).
3 widgets : un dépôt, l’activité récente, le compte avec le quota d’API restant.
Quelques exemples de scènes :
une nouvelle version de Gladys sort → message Telegram avec {{triggerEvent.data.summary}} ;
la CI de mon projet échoue → la lampe du bureau passe au rouge ;
mon dépôt reçoit une étoile → un petit son sur l’enceinte.
Installation
Depuis le store : elle sera disponible dans la journée, le temps de l’indexation.
Ou dès maintenant depuis l’URL du dépôt : Intégrations → Installer une intégration → https://github.com/William-De71/gladys-github.
Il faut Gladys 5.1.0 au minimum.
Configuration :
créez un jeton à granularité fine sur GitHub (accès « Public repositories » en lecture seule, ou vos dépôts privés en lecture) ;
collez-le dans la configuration et listez les dépôts à suivre (propriétaire/nom, séparés par des virgules) ;
cliquez sur « Tester la connexion », puis ajoutez les appareils dans l’onglet Découverte.
Captures et schémas
Schéma d'architecture (illustration)
Ces images sont des illustrations, pas des captures réelles. [Emplacement : captures réelles de la configuration, de la découverte, des widgets et d’une scène à ajouter.]
Limites connues
GitHub ne pousse rien sans webhook public : l’intégration interroge l’API toutes les 2 minutes par défaut (de 60 s à 1 h). C’est aussi le délai des déclencheurs.
Au plus 5 éléments de chaque type sont lus par passage : une très grosse rafale entre deux passages ne déclenche que les plus récents.
GitHub ne donne que le nombre d’étoiles, pas l’auteur.
Rien de ce qui se passe pendant que Gladys est arrêté n’est rejoué au redémarrage.
Testé contre l’API réelle de GitHub et le faux Gladys du SDK. Je ne l’ai pas encore installée dans une vraie instance Gladys : vos retours sont les bienvenus.
Retours
Une issue GitHub ou une réponse dans ce fil. Indiquez la version de Gladys, celle de l’intégration et les journaux de l’intégration (idéalement avec DEBUG=gladys-integration-sdk).
Merci pour ce plugin.
J’aurai bien aimé suivre toutes mes intégrations mais les rentrer une par une c’est pas pratique ^^
J’ai par contre suivi la doc et je me retrouve avec cette erreur quand j’ai mis mon PAT et que je test la connexion :
[2026-10-13T07:23:24.628Z] [WARN] GitHub read failed: GitHub refused the query: Resource not accessible by personal access token
Merci pour le retour ! Les deux points sont traités dans la v0.2.0 (mise à jour dispo depuis Intégrations → GitHub, ou réinstallation depuis l’URL du dépôt).
L’erreur « Resource not accessible by personal access token »
Un jeton à granularité fine n’a pas le droit de lire certaines informations (par exemple les abonnés du compte ou les vérifications CI). GitHub refusait alors toute la requête. Maintenant, l’intégration repère les
informations refusées par le jeton, les retire de sa requête et lit tout le reste normalement : seuls les compteurs concernés ne s’affichent pas. Le journal indique ce qui a été retiré, par exemple :
Not readable with this token, left out: viewer.followers
Si tu as cette ligne, copie-la moi : ça me dira exactement quel champ GitHub refuse aux jetons fins, et je pourrai préciser la doc.
Suivre toutes tes intégrations d’un coup
Dans « Dépôts à suivre », tu peux maintenant écrire un motif au lieu de lister les dépôts un par un :
prohand/* : tous les dépôts du compte (ou d’une organisation) ;
prohand/gladys-* : seulement ceux dont le nom commence par gladys- ;
ça se mélange avec des noms complets : prohand/gladys-*, GladysAssistant/Gladys.
Les forks et les dépôts archivés sont ignorés. La limite reste de 20 dépôts : au-delà, ceux nommés en entier passent d’abord, puis les plus récemment mis à jour (le bouton « Tester la connexion » le signale). La liste est
relue toutes les heures, donc une nouvelle intégration apparaît toute seule dans l’onglet Découverte dans l’heure.
La limite de 20 vient de la constante MAX_REPOSITORIES = 20 (src/github-api.js:26). C’est un choix de conception : GitHub n’impose pas ce chiffre. Voici ce qui la justifie.
Une seule requête par passage. Tous les dépôts suivis sont lus dans une même requête GraphQL. Pour chaque dépôt, elle récupère les compteurs, les 5 dernières issues, PR, releases et commits, la dernière discussion et le
dernier tag. Plus il y a de dépôts, plus la requête est lourde et lente. GitHub coupe les requêtes trop longues (environ 10 s de son côté, 20 s de timeout chez nous). Si ça coupe, c’est tout le passage qui échoue, pas un
seul dépôt.
La charge côté Gladys. Chaque dépôt devient un appareil avec 14 fonctionnalités. Avec 20 dépôts, on a déjà 280 fonctionnalités, dont les états sont publiés à chaque passage (toutes les 120 s par défaut). Ça finit par
encombrer la Découverte, la base et les widgets.
Le quota GitHub. Un jeton dispose de 5 000 points par heure. Le coût d’une requête augmente avec le nombre de connexions demandées (releaseAssets(first: 50) dans chaque release par exemple). Avec 20 dépôts, on reste à
quelques pour cent du quota, même à 60 s. On garde ainsi de la marge pour les autres usages du même jeton.
Un point à corriger au passage : les commentaires du code (src/github-api.js:7-9) et la doc disent qu’une requête coûte « 1 point quel que soit le nombre de dépôts ». C’est probablement faux. D’après la règle de calcul de
GitHub (connexions demandées ÷ 100), 20 dépôts coûteraient plutôt 3 ou 4 points par passage. Je ne l’ai pas vérifié, faute de pouvoir interroger l’API ici. On peut le mesurer en ajoutant cost dans rateLimit { … }. Même dans
ce cas, on reste sous les 5 % du quota.
Si tu as le besoin au-delà de 20, la limite peut être relevée (30 à 50, par exemple). Il faudrait alors mesurer le coût et la durée réels de la requête, ou la découper en plusieurs requêtes par passage.
J’ai fait les mesures : j’ai lancé la vraie requête de l’intégration sur 100 dépôts publics, en deux jeux. Le premier regroupe des dépôts de taille courante (des dépôts « gladys »), le second de gros projets très actifs.
Ce n’est pas le quota GitHub qui bloque. La requête coûte environ 1 point par tranche de 10 dépôts. Même avec 100 dépôts lus toutes les 2 minutes, on resterait sous 7 % des 5 000 points par heure.
Ce qui bloque, c’est la durée de la requête. Chaque dépôt ajoute environ 200 à 250 ms, et GitHub coupe une requête au bout d’environ 10 secondes :
20 dépôts => 4 à 6 s => OK
40 dépôts => 7,5 à 9 s => OK, mais à la limite
60 dépôts => 10 à 11 s => erreurs 502/504 de GitHub
100 dépôts => ~11 s => échec presque à chaque fois
Avec de gros dépôts très actifs, c’est encore pire : dès 15 à 20 dépôts, GitHub renvoie une partie des données vides (RESOURCE_LIMITS_EXCEEDED), surtout les compteurs de téléchargements des releases.
Augmenter simplement la limite ferait donc échouer des passages entiers. La bonne solution, c’est de découper chaque passage en plusieurs petites requêtes d’une dizaine de dépôts. Chacune prendrait environ 5 s et coûterait 1 point. Ça permettrait de monter à 50 dépôts tout en restant autour de 3 % du quota. Ça corrigerait au passage le problème des données vides sur les gros dépôts.
Je m’en occupe dans une prochaine version, je te tiens au courant !
C’est en ligne avec la v0.3.0 : l’intégration peut maintenant suivre jusqu’à 50 dépôts au lieu de 20.
Comme je te l’expliquais, la limite ne venait pas du quota GitHub mais de la durée de la requête : GitHub coupe une requête au bout d’environ 10 secondes. Maintenant, chaque passage lit les dépôts par lots de 10, une petite requête par lot, l’une après l’autre.
Testé sur l’API GitHub réelle avec 50 dépôts
À 120 secondes d’intervalle, ça représente environ 3 % des 5 000 points par heure que GitHub accorde à un jeton.
Ça corrige aussi un bug : avec beaucoup de gros dépôts actifs, GitHub renvoyait certaines données vides sans prévenir, en particulier les compteurs de téléchargements des releases. Ça n’arrive plus avec des lots de 10.
Les motifs prohand/* profitent aussi de la nouvelle limite. Au-delà de 50 dépôts, ceux que tu as nommés en entier passent en premier, puis les plus récemment mis à jour.
Mets à jour l’intégration et dis-moi si tout remonte bien chez toi !
