Intégration domotique GitHub, gratuite et open source
Suivez vos dépôts GitHub : versions, issues, étoiles, CI, scènes et widgets.
Publiée par William-De71
- Appareils
- Version 0.3.0
- Nécessite Gladys >=5.1.0
- ★ 0
Présentation
Suivez vos dépôts GitHub depuis Gladys : chaque dépôt devient un appareil avec ses étoiles, ses forks, ses issues et pull requests ouvertes, et sa dernière version, son dernier tag, commit, issue, pull request et discussion. Les scènes réagissent à une nouvelle version, issue, pull request, discussion, à un commit, à une étoile, ou aux vérifications (CI) de la branche par défaut. Trois widgets de tableau de bord montrent un dépôt, l'activité récente et votre compte.
L'intégration interroge l'API de GitHub (cloud) : rien d'autre ne sort de votre réseau, et elle ne fait que lire, elle n'écrit jamais sur GitHub.
Prérequis
- Gladys Assistant 5.1.0 ou plus récent.
- Un compte GitHub et un jeton d'accès personnel. Un jeton à granularité fine avec l'accès « Public repositories » (lecture seule) suffit pour les dépôts publics. Pour des dépôts privés, sélectionnez-les et accordez en lecture seule « Metadata », « Contents », « Issues », « Pull requests » et « Discussions ». Un jeton classique sans aucune portée fonctionne aussi pour les dépôts publics.
Configuration
- Créez le jeton sur github.com/settings/personal-access-tokens/new.
- Ouvrez Intégrations → GitHub, collez le jeton et listez les dépôts à suivre.
- Enregistrez, puis cliquez sur Tester la connexion : elle affiche votre compte, le quota d'API restant et les dépôts lus.
| Champ | Description |
|---|---|
| Jeton d'accès personnel | Obligatoire. Jamais réaffiché, jamais écrit dans les journaux. |
| Dépôts à suivre | propriétaire/nom ou le lien github.com, ou un motif propriétaire/*, séparés par des virgules, 50 au maximum. |
| Intervalle de lecture (s) | De 60 à 3600, 120 par défaut. C'est aussi le délai des déclencheurs de scène. |
| Langue des textes | Noms des appareils et résumés des scènes. Automatique : la langue de votre tableau de bord. |
Pour suivre tous les dépôts d'un compte ou d'une organisation sans les saisir un par un, écrivez propriétaire/*, ou propriétaire/gladys-* pour ceux dont le nom commence par gladys-. Les forks et les dépôts archivés sont ignorés. Les motifs se combinent avec des noms complets, par exemple prohand/gladys-*, GladysAssistant/Gladys. Au-delà de 50 dépôts, les dépôts nommés en entier passent en premier, puis les plus récemment mis à jour. La liste est relue toutes les heures : un nouveau dépôt apparaît dans la Découverte dans l'heure.
Chaque passage lit les dépôts par lots de 10, une requête par lot : avec 50 dépôts à 120 secondes, l'intégration utilise environ 3 % des 5 000 points par heure que GitHub accorde à un jeton.
Utilisation
Appareils
Dans l'écran Découverte, ajoutez les dépôts et votre compte. Un dépôt propose : étoiles, forks, abonnés, issues ouvertes, pull requests ouvertes, pull requests fusionnées, discussions, téléchargements de la dernière version (si elle a des fichiers), et en texte la dernière version, le dernier tag, commit, issue, pull request et discussion. Le compte propose abonnés, abonnements, dépôts publics et gists publics.
Déclencheurs de scène
| Déclencheur | Filtres | Variables |
|---|---|---|
| Version publiée | dépôt, version ou préversion | nom, tag, auteur, lien, résumé |
| Issue ouverte | dépôt | numéro, titre, auteur, lien, résumé |
| Pull request ouverte | dépôt | numéro, titre, auteur, brouillon, lien, résumé |
| Discussion lancée | dépôt | numéro, titre, auteur, lien, résumé |
| Nouveau commit | dépôt | branche, SHA, message, auteur, lien, résumé |
| Nouvelle étoile | dépôt | étoiles, étoiles ajoutées, lien, résumé |
| Vérifications terminées | dépôt, réussies ou en échec | branche, SHA, message, lien, résumé |
Exemples :
- Quand une version d'un projet que vous utilisez sort → envoyez-vous un message avec
{{triggerEvent.data.summary}}. - Quand les vérifications de votre projet échouent → passez la lampe du bureau en rouge.
- Quand votre dépôt reçoit une étoile → jouez un son sur l'enceinte.
La première lecture après un démarrage sert de référence : rien de ce qui s'est passé pendant que Gladys était arrêté n'est rejoué.
Action de scène
GitHub : lire un dépôt renvoie ses étoiles, forks, abonnés, issues et pull requests ouvertes, sa dernière version (et son lien), son dernier commit, ses vérifications et une phrase de résumé. Un compteur inconnu vaut -1.
Widgets
- Dépôt GitHub : étoiles, forks, issues, pull requests, dernière version, vérifications de la branche par défaut et un lien.
- Activité GitHub : les dernières versions, issues, pull requests et commits de tous les dépôts (ou d'un seul), avec un filtre.
- Compte GitHub : abonnés, abonnements, dépôts publics et quota d'API restant.
Dépannage
- « GitHub a refusé le jeton » : le jeton a expiré ou a été révoqué : créez-en un nouveau.
- « Introuvable ou refusé par le jeton » : vérifiez l'orthographe du dépôt, ou donnez-lui accès au jeton (dépôt privé).
- « Quota de l'API GitHub épuisé » : un autre outil utilise le même jeton : augmentez l'intervalle de lecture ou utilisez un jeton dédié. La lecture reprend d'elle-même.
- Pas d'auteur pour les étoiles : GitHub ne donne à l'intégration que le nombre d'étoiles, pas qui les a ajoutées.
- Pour signaler un problème, ouvrez une issue sur GitHub avec les versions de Gladys et de l'intégration et les journaux (
DEBUG=gladys-integration-sdk).
Paramètres de configuration
Voici les paramètres demandés par GitHub dans son écran de configuration dans Gladys.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| Accès à GitHub | section | Non | L’intégration lit GitHub avec un jeton d’accès personnel. Créez un jeton à granularité fine : l’accès « Public repositories » suffit, en lecture seule. Pour suivre des dépôts privés, sélectionnez-les et accordez « Metadata », « Contents », « Issues », « Pull requests » et « Discussions » en lecture seule. Copiez le jeton ci-dessous. |
| Jeton d’accès personnel | secret | Oui | Commence par github_pat_ (granularité fine) ou ghp_ (classique, sans portée). |
| Dépôts | section | Non | Chaque dépôt suivi devient un appareil dans l’écran de découverte, à côté d’un appareil pour votre compte. Les déclencheurs de scène et les widgets les choisissent par appareil. |
| Dépôts à suivre | string | Non | propriétaire/nom ou le lien github.com, séparés par des virgules (50 au maximum). propriétaire/* suit tous les dépôts d’un compte, propriétaire/gladys-* ceux qui commencent par gladys-. |
| Intervalle de lecture (s) | number | Non | Fréquence de lecture de GitHub, entre 60 et 3600 secondes. C’est aussi le délai de réaction des déclencheurs de scène. |
| Langue des textes | select | Non | Noms des appareils, résumés et sorties des scènes. Automatique : la langue de votre tableau de bord, dès qu’un widget GitHub a été affiché. |
Comment installer GitHub dans Gladys
- Dans Gladys, ouvrez Intégrations : GitHub apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
- Cliquez sur Installer. Gladys télécharge l'image Docker (
ghcr.io/william-de71/gladys-github:0.3.0), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration). - Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
- Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/William-De71/gladys-github.
GitHub nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.
Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.
À propos des intégrations externes
GitHub est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par William-De71, et non par l'équipe cœur de Gladys.
- Parcourir toutes les intégrations externes
- Découvrir les intégrations natives intégrées à Gladys
- Créer et publier votre propre intégration externe
- Code source sur GitHub — source de cette documentation