GitHub App einrichten

Eine GitHub App ist der von GitHub empfohlene Weg, einem Dienst begrenzten Zugriff auf ein Repository zu geben. Anders als ein persönliches Zugriffstoken hat sie eine eigene Identität (pullpress[bot]), ihre Berechtigungen sind fest und sichtbar, und Sie können sie auf genau die Repositorys beschränken, die Sie wählen.

Welche Berechtigungen sie anfragt

Bei der Installation zeigt GitHub die vollständige Liste der Berechtigungen. Sie ist bewusst kurz:

• Contents: lesen und schreibenIhre Inhaltsdateien lesen und die Änderungen der Redakteure auf Branches committen.
• Pull requests: lesen und schreibenDie Pull Requests, die Redakteure einreichen, öffnen, aktualisieren und mit Labels versehen.
• Metadata: lesenGrundlegende Repository-Informationen (Name, Standard-Branch). Für jede GitHub App vorgeschrieben.
• Organization members: lesenNur genutzt, um zu prüfen, ob die verbindende Person Eigentümer Ihrer GitHub-Organisation ist; nur dann darf sie eine Installation von einem Arbeitsbereich abziehen, dem sie nicht gehören sollte.
• Checks: lesen (optional)Lässt das Dashboard anzeigen, ob Ihre Site nach einer Änderung gerade gebaut wird oder online ist. Ohne diese Berechtigung funktioniert alles andere genauso.
• Workflows, Actions, Einstellungen, SecretsAusdrücklich nicht angefragt. PullPress kann Ihre CI, Repository-Einstellungen, Webhooks oder Secrets nicht ändern.

Auf einem Repository installieren

• Wählen Sie in Ihrem PullPress-Dashboard Website verbinden (oder Site verbinden auf der Seite Sites & GitHub). Sie werden zum Installationsbildschirm von GitHub geschickt.
• Wählen Sie das Konto oder die Organisation, der das Repo gehört, dann Only select repositories und das eine Repository Ihrer Site. Weitere können Sie später jederzeit hinzufügen.
• Prüfen Sie die Berechtigungen und bestätigen Sie. GitHub bittet Sie, PullPress für Ihr GitHub-Konto zu autorisieren, und leitet Sie zurück.

Mit diesem Autorisierungsschritt prüft PullPress, dass Sie wirklich Zugriff auf die Installation haben, bevor sie mit Ihrem Arbeitsbereich verknüpft wird: Es fragt GitHub, welche Installationen der App Ihr GitHub-Konto erreichen kann, und akzeptiert nur diese. Niemand kann Ihre Repositorys an seinen Arbeitsbereich hängen, indem er eine Installationsnummer errät, und eine Installation, die ein anderer GitHub-Nutzer schon mit einem anderen Arbeitsbereich verbunden hat, wird abgelehnt.

Zugriff auf eine Installation ist kein Zugriff auf jedes Repository darin, daher fragt PullPress GitHub auch, in welche Repositorys Ihr Konto pushen darf. Nur diese werden beim Hinzufügen einer Site angeboten, und die Prüfung wird auf dem Server wiederholt. Sie bleibt eine Woche gültig; danach prüft ein Klick auf Meinen Repository-Zugriff aktualisieren sie erneut bei GitHub.

Gibt es eine Site einmal, arbeitet sie über die App weiter, auch wenn die Person, die GitHub verbunden hat, später Ihre Organisation verlässt. Deshalb bittet PullPress alle 180 Tage einen Administrator des Arbeitsbereichs, die Verbindung erneut zu bestätigen: Die Seite Sites zeigt zwei Wochen vorher Erneut bestätigen bis…, Eigentümer und Administratoren bekommen eine E-Mail, und Mit GitHub bestätigen neben der Installation erledigt es mit einem Klick. Es ist nur eine Erinnerung: Bearbeiten und Veröffentlichen werden nie blockiert.

Zurück in PullPress bestätigt der Verbindungsbildschirm zuerst, welches Konto die Installation abdeckt und wie viele Repositorys sie erreicht, mit einem direkten Link, um die Installation auf GitHub zu ändern, falls sie beim falschen Konto oder bei den falschen Repositorys gelandet ist. Brechen Sie den GitHub-Ablauf mittendrin ab, zeigt PullPress einen freundlichen Hinweis, dass die Installation nicht abgeschlossen wurde, mit einem Link zum erneuten Versuch, statt stillschweigend zu scheitern.

Administratoren einer Organisation können die App auch für eine Kollegin oder einen Kollegen installieren. Diese Person öffnet dann den Verbindungsbildschirm (oder die Seite Sites) und wählt Mit GitHub bestätigen (oder Bestehende Installation verbinden): GitHub bestätigt den Zugriff, und die Installation ist einsatzbereit. Erreicht Ihr GitHub-Konto mehrere Installationen, wählen Sie die, die dieser Arbeitsbereich nutzen soll; PullPress verbindet nie alle auf einmal. Installationen, die vor dieser Prüfung verbunden wurden, verlangen dieselbe einmalige Bestätigung, bevor darauf neue Sites hinzugefügt werden können.

Beantragt ein Mitglied der Organisation die App, statt sie zu installieren, meldet PullPress, dass der Antrag auf einen Eigentümer der Organisation wartet; nach der Genehmigung nutzen Sie Bestehende Installation verbinden.

Trennen und übernehmen

Eigentümer eines Arbeitsbereichs können eine Installation auf der Seite Sites Trennen, sobald keine aktive Site sie mehr nutzt. Auf GitHub ändert sich nichts.

Hält ein anderer PullPress-Arbeitsbereich eine Installation auf Ihrem GitHub-Konto oder Ihrer Organisation, kann ein Eigentümer dieses Kontos sie in seinen eigenen Arbeitsbereich verschieben (als Eigentümer eines PullPress-Arbeitsbereichs; Administratoren des Arbeitsbereichs sehen die Option, brauchen aber einen Eigentümer zur Bestätigung): GitHub bestätigt, dass die Person Eigentümer ist, die Sites des anderen Arbeitsbereichs auf dieser Installation werden archiviert (schreibgeschützt), und dessen Eigentümer bekommen eine E-Mail. Sowohl Trennen als auch Übernehmen werden im Protokoll des Arbeitsbereichs festgehalten.

Wie aus einer Installation eine Site wird

Ein verbundenes Repository wird eine Site in PullPress. Die Site liest ihr Inhaltsmodell aus der pullpress.config.yml des Repos, und jeder Redakteur, den Sie einladen, wird gezielt zu dieser Site eingeladen. Agenturen mit vielen Kunden-Repos bekommen eine Site pro Repo, alle im Dashboard für mehrere Sites sichtbar, jede mit eigenen Redakteuren und Rollen.

Hinweise zur Sicherheit

• Erlaubte Pfade. Änderungen von Redakteuren werden nur in die Ordner geschrieben, die Ihre Konfiguration angibt: Sammlungsordner und der Medienordner. Darüber hinaus schreibt PullPress nur zwei eigene Dateien: seine pullpress.config.yml (wenn ein Administrator die Konfiguration einrichtet oder bearbeitet) und, falls Sie sie nutzen, eine llms.txt im Stammverzeichnis des Repositorys. Konfigurationsänderungen und die automatische Pflege einer vorhandenen llms.txt auf Sites mit direkter Veröffentlichung werden direkt auf Ihren Standard-Branch committet; die Schaltfläche „llms.txt aktualisieren“ auf anderen Sites geht durch die Prüfung. Alles andere, auch .github/, wird abgelehnt.
• Keine Tokens im Browser. Die Browser der Redakteure sprechen nur mit PullPress. GitHub-Zugangsdaten sind kurzlebige Installationstokens, die serverseitig existieren und nie an den Client geschickt werden. Die GitHub-Autorisierung, die beim Verbinden den Zugriff prüft, läuft mit PKCE und wird widerrufen, sobald die Prüfung fertig ist; PullPress speichert keine GitHub-Nutzertokens.
• Jede Änderung ist zuordenbar. Commits und Pull Requests werden von pullpress[bot] erstellt und dem Redakteur gutgeschrieben, der sie gemacht hat, damit Ihre Git-Historie aussagekräftig bleibt. Standardmäßig ist der Autor der Name des Redakteurs mit einer pseudonymen No-Reply-Adresse (id+name@users.noreply.…), sodass E-Mail-Adressen nie in der Historie eines öffentlichen Repositorys landen. Ein Site-Administrator kann unter Site-Einstellungen → Echte E-Mail-Adressen der Redakteure in der Git-Historie verwenden auf echte Adressen umstellen.
• Mit einem Klick widerrufbar. Deinstallieren Sie die App jederzeit in Ihren GitHub-Einstellungen. Der Zugriff endet sofort, und Ihre Inhalte bleiben genau, wo sie sind. PullPress merkt es auch: Eine deinstallierte oder gesperrte Installation erscheint als Status-Abzeichen in der Site-Liste und als Hinweis im Dashboard, und die Administratoren des Arbeitsbereichs bekommen innerhalb weniger Minuten eine E-Mail. Nichts geht stillschweigend kaputt.
• Branch-Vorschauen bauen Inhalte von Redakteuren. Änderungen, die auf Prüfung warten, liegen auf einem eigenen Branch. Baut Ihr Hoster eine Vorschau jedes Branches (Netlify, Vercel, Cloudflare Pages…), führt diese Vorschau den Build Ihrer Site mit noch nicht geprüften Inhalten aus. PullPress verhindert, dass Redakteure Skripte oder MDX-Code hinzufügen, und nur echte JPG-/PNG-/WebP-Bilder können hochgeladen werden. Geben Sie Vorschau- oder Branch-Builds trotzdem keine Produktions-Secrets, und behalten Sie Administratorrechte (wer Code hinzufügen darf) Personen vor, denen Sie vertrauen.
• Fehlende Berechtigungen werden benannt. Fehlt der App einmal eine nötige Berechtigung (etwa nach einem aktualisierten Berechtigungssatz, den Sie noch nicht angenommen haben), nennt die Fehlermeldung genau den fehlenden Scope, statt allgemein zu scheitern.

Nächster Schritt: Beschreiben Sie Ihre Inhalte in pullpress.config.yml, oder gehen Sie die ganze Einrichtung unter Erste Schritte durch.