GitHub Smart-Home-Integration, kostenlos und Open Source
GitHub-Repositorys verfolgen: Releases, Issues, Sterne, CI, Szenen und Widgets.
Veröffentlicht von William-De71
- Geräte
- Version 0.3.0
- Erfordert Gladys >=5.1.0
- ★ 0
Überblick
Verfolge GitHub-Repositorys in Gladys: Jedes Repository wird zu einem Gerät mit seinen Sternen, Forks, offenen Issues und Pull-Requests sowie seinem neuesten Release, Tag, Commit, Issue, Pull-Request und seiner neuesten Diskussion. Szenen reagieren auf ein neues Release, Issue, einen Pull-Request, eine Diskussion, einen Commit, einen Stern oder auf die Prüfungen (CI) des Standard-Branches. Drei Dashboard-Widgets zeigen ein Repository, die neueste Aktivität und dein Konto.
Die Integration liest die GitHub-API (Cloud): Sonst verlässt nichts dein Netzwerk, und sie liest nur, sie schreibt nie auf GitHub.
Voraussetzungen
- Gladys Assistant 5.1.0 oder neuer.
- Ein GitHub-Konto und ein persönliches Zugriffstoken. Ein feingranulares Token mit dem Zugriff „Public repositories“ (nur lesend) genügt für öffentliche Repositorys. Für private Repositorys wähle sie aus und erteile nur lesend „Metadata“, „Contents“, „Issues“, „Pull requests“ und „Discussions“. Ein klassisches Token ohne Bereich funktioniert für öffentliche Repositorys ebenfalls.
Konfiguration
- Erstelle das Token auf github.com/settings/personal-access-tokens/new.
- Öffne Integrationen → GitHub, füge das Token ein und liste die zu verfolgenden Repositorys auf.
- Speichere und klicke dann auf Verbindung testen: Es zeigt dein Konto, das verbleibende API-Limit und die gelesenen Repositorys.
| Feld | Beschreibung |
|---|---|
| Persönliches Zugriffstoken | Pflichtfeld. Wird nie wieder angezeigt und nie protokolliert. |
| Zu verfolgende Repositorys | Besitzer/Name oder der github.com-Link, oder ein Muster Besitzer/*, durch Kommas getrennt, höchstens 50. |
| Abfrageintervall (s) | 60 bis 3600, standardmäßig 120. Auch die Reaktionszeit der Szenenauslöser. |
| Sprache der Texte | Gerätenamen und Szenen-Zusammenfassungen. Automatisch: die Sprache deines Dashboards. |
Um alle Repositorys eines Kontos oder einer Organisation zu verfolgen, ohne sie einzeln einzugeben, schreibe Besitzer/*, oder Besitzer/gladys-* für die, deren Name mit gladys- beginnt. Forks und archivierte Repositorys werden ausgelassen. Muster lassen sich mit vollständigen Namen kombinieren, zum Beispiel prohand/gladys-*, GladysAssistant/Gladys. Bei mehr als 50 Repositorys kommen die vollständig genannten zuerst, dann die zuletzt aktualisierten. Die Liste wird stündlich neu gelesen: Ein neues Repository erscheint innerhalb einer Stunde im Reiter Entdecken.
Jede Runde liest die Repositorys in Gruppen von 10, eine Anfrage pro Gruppe: Mit 50 Repositorys bei 120 Sekunden nutzt die Integration etwa 3 % der 5.000 Punkte pro Stunde, die GitHub einem Token gewährt.
Verwendung
Geräte
Füge im Reiter Entdecken die Repositorys und dein Konto hinzu. Ein Repository bietet: Sterne, Forks, Beobachter, offene Issues, offene Pull-Requests, gemergte Pull-Requests, Diskussionen, Downloads des neuesten Releases (wenn es Dateien hat) sowie als Text das neueste Release, Tag, Commit, Issue, Pull-Request und die neueste Diskussion. Das Konto bietet Follower, gefolgte Konten, öffentliche Repositorys und öffentliche Gists.
Szenenauslöser
| Auslöser | Filter | Variablen |
|---|---|---|
| Release veröffentlicht | Repository, Release oder Vorabversion | Name, Tag, Autor, Link, Zusammenfassung |
| Issue eröffnet | Repository | Nummer, Titel, Autor, Link, Zusammenfassung |
| Pull-Request eröffnet | Repository | Nummer, Titel, Autor, Entwurf, Link, Zusammenfassung |
| Diskussion gestartet | Repository | Nummer, Titel, Autor, Link, Zusammenfassung |
| Neuer Commit | Repository | Branch, SHA, Nachricht, Autor, Link, Zusammenfassung |
| Neuer Stern | Repository | Sterne, neue Sterne, Link, Zusammenfassung |
| Prüfungen abgeschlossen | Repository, bestanden oder fehlgeschlagen | Branch, SHA, Nachricht, Link, Zusammenfassung |
Beispiele:
- Wenn ein Release eines Projekts erscheint, das du nutzt → schicke dir eine Nachricht mit
{{triggerEvent.data.summary}}. - Wenn die Prüfungen deines Projekts fehlschlagen → schalte die Bürolampe auf Rot.
- Wenn dein Repository einen Stern bekommt → spiele einen Ton auf dem Lautsprecher ab.
Die erste Abfrage nach einem Start dient als Referenz: Was passiert ist, während Gladys aus war, wird nicht nachgeholt.
Szenenaktion
GitHub: Repository lesen liefert Sterne, Forks, Beobachter, offene Issues und Pull-Requests, das neueste Release (und seinen Link), den neuesten Commit, die Prüfungen und einen zusammenfassenden Satz. Ein unbekannter Zähler ist -1.
Widgets
- GitHub-Repository: Sterne, Forks, Issues, Pull-Requests, neuestes Release, Prüfungen des Standard-Branches und ein Link.
- GitHub-Aktivität: die neuesten Releases, Issues, Pull-Requests und Commits aller Repositorys (oder eines), filterbar.
- GitHub-Konto: Follower, gefolgte Konten, öffentliche Repositorys und das verbleibende API-Limit.
Fehlerbehebung
- „GitHub hat das Token abgelehnt“: Das Token ist abgelaufen oder wurde widerrufen: Erstelle ein neues.
- „Nicht gefunden oder vom Token nicht erlaubt“: Prüfe die Schreibweise des Repositorys oder gib dem Token Zugriff darauf (privates Repository).
- „GitHub-API-Limit erschöpft“: Ein anderes Werkzeug nutzt dasselbe Token: Erhöhe das Abfrageintervall oder nutze ein eigenes Token. Das Lesen geht von selbst weiter.
- Kein Autor bei Sternen: Die Integration erhält von GitHub nur die Zahl der Sterne, nicht, wer sie vergeben hat.
- Um ein Problem zu melden, eröffne ein Issue auf GitHub mit den Versionen von Gladys und der Integration und den Protokollen (
DEBUG=gladys-integration-sdk).
Konfigurationseinstellungen
Diese Einstellungen fragt GitHub in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Zugriff auf GitHub | section | Nein | Die Integration liest GitHub mit einem persönlichen Zugriffstoken. Erstelle ein feingranulares Token: Der Zugriff „Public repositories“ genügt, nur lesend. Um private Repositorys zu verfolgen, wähle sie aus und erteile „Metadata“, „Contents“, „Issues“, „Pull requests“ und „Discussions“ nur lesend. Kopiere das Token hierher. |
| Persönliches Zugriffstoken | secret | Ja | Beginnt mit github_pat_ (feingranular) oder ghp_ (klassisch, ohne Bereich). |
| Repositorys | section | Nein | Jedes verfolgte Repository wird zu einem Gerät im Reiter Entdecken, neben einem Gerät für dein Konto. Szenenauslöser und Widgets wählen sie über das Gerät aus. |
| Zu verfolgende Repositorys | string | Nein | Besitzer/Name oder der github.com-Link, durch Kommas getrennt (höchstens 50). Besitzer/* verfolgt alle Repositorys eines Kontos, Besitzer/gladys-* die mit gladys- beginnenden. |
| Abfrageintervall (s) | number | Nein | Wie oft GitHub gelesen wird, zwischen 60 und 3600 Sekunden. Das ist auch die Reaktionszeit der Szenenauslöser. |
| Sprache der Texte | select | Nein | Gerätenamen, Zusammenfassungen und Ausgaben der Szenen. Automatisch: die Sprache deines Dashboards, sobald ein GitHub-Widget angezeigt wurde. |
So installierst du GitHub in Gladys
- Öffne in Gladys Integrationen: GitHub erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/william-de71/gladys-github:0.3.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/William-De71/gladys-github.
GitHub benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
GitHub ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von William-De71 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle externen Integrationen durchsuchen
- Die nativen Integrationen entdecken, die in Gladys eingebaut sind
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation