Die GitHub-Prüfung für Pull Requests

Eine Änderung am Warenkorb-Template besteht das Code-Review, die Tests sind grün, und eine Woche später fehlt purchase im Report. Die Prüfung in Pull Requests verlegt diesen Moment vor den Merge: Wir spielen jeden Pull Request auf seiner Preview-Umgebung mit denselben Journeys ab, die Sie in der Produktion überwachen, und schreiben das Ergebnis als Check mit dem Namen AnalyticsProof auf GitHub.

Was Sie brauchen

• Ein Projekt im Enterprise-Plan und einen Website- oder HbbTV-Test mit mindestens einer aufgezeichneten Journey. Die Schaltfläche „GitHub verbinden“ finden Sie auf der Seite des Tests. Die GitHub-Verbindung können Bearbeiter und höher ändern; alle anderen sehen die Schaltfläche ausgegraut.
• Eine Preview-Umgebung, die für jeden Pull Request unter einer eigenen https-Adresse bereitsteht. Sie darf hinter einem Passwort oder einer IP-Allowlist liegen; beides stellen Sie im dritten Schritt ein.
• Journeys, die in der Zeitzone des Scan-Landes aufgezeichnet wurden. Passt eine nicht, nennt der Dialog sie und empfiehlt, sie vor dem Aktivieren neu aufzuzeichnen.

Die Einrichtung hat drei Schritte: Repository, Preview-URL und Zugang.

Schritt 1: Repository

Klicken Sie auf „GitHub autorisieren“. In einem neuen Tab erlauben Sie den Zugriff auf GitHub; danach sehen wir die Repositories, die Sie ändern dürfen. Ist die AnalyticsProof App in Ihrer Organisation noch nicht installiert, erscheint der Link „AnalyticsProof App auf GitHub verbinden“. Wählen Sie bei der Installation „Only select repositories“ und haken Sie nur das Repository der Website an. Zurück im Dialog nutzen Sie „Repositories aktualisieren“ und wählen es unter „Website-Repository“ aus.

Schritt 2: Preview-URL

Unter „Woher die Preview-URL kommt“ gibt es zwei Möglichkeiten.

Aus GitHub Deployments. Passt, wenn Ihr Hosting oder Ihre Pipeline die Deployments von Pull Requests an GitHub meldet. Wir warten auf ein Deployment des Commits aus dem Pull Request mit dem Status success und einer Umgebungs-URL (environment_url). Bis es da ist, zeigt der Check, dass er auf die Adresse wartet. Kommt innerhalb von 10 Minuten nach dem Start des Checks nichts, endet der Check neutral.

Aus einer URL-Vorlage. Passt, wenn die Preview-Adresse vorhersehbar ist. Die Vorlage kennt diese Platzhalter:

Unter dem Feld sehen Sie sofort, wie die Adresse für den Branch feature/checkout aussähe. Die Vorlage muss per https:// auf eine öffentliche Domain führen, ohne Portnummer, ohne Benutzername und Passwort in der Adresse und ohne IP-Adresse. Lokale Namen (.local, .internal, .test, .example und ähnliche) lehnt der Dialog ab. Eine Vorlage ganz ohne Platzhalter wird angenommen, aber der Dialog weist darauf hin, dass dann jeder Pull Request gegen dieselbe Adresse getestet wird.

Schritt 3: Zugang

Passwort der Preview. Liegt die Preview hinter Basic Auth, haken Sie „Die Preview verlangt Benutzername und Passwort (Basic Auth)“ an und füllen beides aus. Der Browser schickt die Daten nur an den Origin der Preview, nie an andere Dienste auf der Seite. Das Passwort wird als Klartext gespeichert, und Bearbeiter können es im Dialog lesen. Nehmen Sie deshalb einen eigenen Zugang nur für die Preview, kein persönliches Konto.

IP-Allowlist. Im Feld „Erlauben Sie unsere IP“ steht die Adresse, von der wir scannen. Sie richtet sich nach dem Land, das beim Anlegen des Tests gewählt wurde, und auch die Scans der Pull Requests kommen von dort. Tragen Sie sie in die Allowlist der Preview-Umgebung ein.

„Prüfen und speichern“ versucht zuerst, die Preview zu öffnen: DNS, TLS-Handshake, HTTP-Antwort, Seiten-Rendering und DataLayer. Gespeichert wird nur, wenn diese Prüfung besteht. Schlägt sie fehl, sehen Sie, an welchem Schritt und was zu tun ist.

In diesem Moment gibt es noch keinen Pull Request, deshalb nimmt die Prüfung den Standard-Branch des Repositorys und dessen letzten Commit. In die Vorlage kommt der Name des Standard-Branches, und {pr} wird zu null. Eine Vorlage, die nur auf der Nummer des Pull Requests aufbaut, besteht also nur, wenn diese Adresse existiert. Bei GitHub Deployments braucht der letzte Commit des Standard-Branches ein erfolgreiches Deployment. Fehlt es, bietet der Dialog „Trotzdem speichern“ an.

Nach dem Speichern bietet der Dialog „Prüfung ausführen“ an. Sie spielt die Journeys gegen dieselbe Adresse ab wie die Prüfung, und „Ergebnisse öffnen“ führt zum Ergebnis im Dashboard. So testen Sie die ganze Einrichtung am schnellsten, bevor ein Kollege ihr in seinem Pull Request begegnet.

Was der Check meldet

Der Check läuft, wenn ein Pull Request geöffnet, mit einem neuen Push aktualisiert, wieder geöffnet oder als bereit für das Review markiert wird. Ein Entwurf (Draft) bekommt einen neutralen Check und wird abgespielt, sobald er bereit für das Review ist. Ein Ergebnis für einen älteren Commit wird nicht geschrieben, wenn inzwischen ein neuerer Push da ist.

• Alle aktiven Journeys des Tests werden abgespielt, jede ab der Preview-URL. Sie laufen als Dry-Run: Es entstehen Abweichungen und ein Ergebnis für den Check, aber in die Journey und ihren erwarteten Zustand wird nichts geschrieben. Mehr zum Dry-Run steht in der API-Referenz.
• Es zählt nur, was die Website direkt in window.dataLayer schreibt. Anfragen, die Tools wie GA4 daraus weiterschicken, bleiben im Dashboard; für sie ist ein Entwickler, der die Website ändert, nicht direkt verantwortlich.
• Bewertet wird nur, was der Pull Request mitbringt. Die Abweichungen werden mit dem letzten Produktionsscan der Journey verglichen, und der Kommentar im Pull Request trennt sie in „New in this PR“ und „Already on production“. Wurde die Produktion noch nie gescannt, gilt alles als neu.
• Nur kritische Änderungen blockieren. Typisch ist ein Event, das der erwartete Zustand verlangt und das im Schritt fehlt (sofern Sie es nicht als optional markiert haben). Ein neues Event, ein fehlender Parameter oder ein anderer Parametertyp sind Warnungen: Der Kommentar führt sie auf, der Check bleibt aber grün. Werte von Parametern vergleichen wir nicht, nur ihr Vorhandensein und ihren JavaScript-Typ.
• Eine Journey, die nicht gemessen werden konnte, ist nicht grün. Schlägt der Scan einer Journey fehl oder misst er nichts, wird der Check rot, auch ohne eine einzige Änderung. Eine Journey, die ihren letzten Schritt nicht erreicht, ist nur eine Warnung: Wahrscheinlich hat sie eine größere Änderung der Website unterbrochen, nicht dieser Pull Request.

Check und Kommentar sind auf Englisch, egal in welcher Sprache Ihr Dashboard läuft. Sie werden von den Reviewern des Repositorys gelesen, und der Name des Checks muss für den Branch-Schutz stabil bleiben.

Den Check verpflichtend machen

Sobald der Check einmal bestanden hat, können Sie ihn auf GitHub als erforderlich festlegen. Aktivieren Sie in den Branch-Protection-Regeln oder in einem Ruleset des Repositorys erforderliche Status-Checks und wählen Sie AnalyticsProof. GitHub bietet nur Checks an, die im Repository kürzlich gelaufen sind, deshalb geht das erst nach dem ersten Lauf.

Beachten Sie, dass GitHub ein neutrales Ergebnis als erfüllt wertet. Ein Pull Request, für den keine Preview gefunden wurde, ein Entwurf oder ein Pull Request, bei dem sich keine Journey vergleichen ließ, blockiert den Merge also nicht.

Wenn der Check nicht tut, was Sie erwarten

Eine häufige Ursache für einen roten Check liegt aber gar nicht im dataLayer. Die Preview weist unseren Browser ab, weil die IP auf der Allowlist fehlt oder das Passwort nicht stimmt. Führen Sie „Prüfen und speichern“ erneut aus; es zeigt genau, an welchem Schritt der Zugang scheitert.

Kein GitHub, oder wollen Sie Ihr eigenes Gate bauen? Dasselbe leistet die API: Die Anleitung CI/CD mit der API beschreibt den Ablauf, die CI-Rezepte sind fertig zum Übernehmen.