Konzepte

Wie wkdoadogit arbeitet: was ein Mount ist, woran die Sichtbarkeit eines Repositorys hängt und wo die Grenzen des Pakets verlaufen. Was Sie tun wollen, steht auf ADO-Git; was Sie nachschlagen wollen, in der Technischen Referenz.

Zweck

Bindet Azure-DevOps-gehostete Git-Repositories ins Wiki ein: Repos browsen, Quellcode rendern, editieren und committen sowie git clone, pull und push über einen Proxy — alles über einen einzigen ADO-Service-Account, sodass Leser und Editoren keine eigene ADO-Lizenz brauchen. Die Autorisierungsgrenze ist die native DokuWiki-ACL, nicht eine ADO-Lizenz.

Zielgruppe: Administratoren und Editoren, die ADO-Code im Wiki sichtbar oder bearbeitbar machen.

Drei Schritte, die das Plugin nicht selbst tut

Ein Repository wird erst sichtbar, wenn drei getrennte Handlungen erfolgt sind. Keine davon löst die nächste aus.

Handlung	Wo	Was entsteht
Verbindung	`do=wkdoado` auf einer Seite des DWDO-Projekts	Beschreibung des ADO-Servers mit Schlüssel und Secret-Verweis
Mount	Administration > ADO-Git Repo-Mounts	Bindung Repository ↔ Namespace und die ACL dafür
Marke auf einer Seite	beliebige Seite innerhalb des DWDO-Projekts	die einzige Darstellung des Repositorys; der Mount legt keine Seite an

Den vollständigen Ablauf mit Beispiel zeigt Ein ADO-Repository erstmals im Wiki anzeigen.

Repo-Mounts

Ein Mount verknüpft ein ADO-Repository mit einem DokuWiki-Namespace der Form code:{projekt}:{repo}, zum Beispiel code:dokuwiki-plugins:wkdoadogit. Erst ein registrierter Mount macht ein Repository erreichbar; jeder Zugriffspfad — Browser, Quellcode-Darstellung, git-Proxy und ZIP-Download — prüft die DokuWiki-ACL gegen diesen Namespace.

Der Mount-Namespace ist virtuell: es entsteht dort keine Wiki-Seite. Trägt die Vorlage den Platzhalter {lang}, bleibt der Mount ein Datensatz, die Regeln aber werden für jede Sprache aus der Einstellung mount_languages geschrieben (Vorgabe de,en,hr,it,sl).

Ein Mount macht ein Repository erreichbar, nicht sichtbar. Gerendert wird es ausschließlich dort, wo ein Autor die Marke {{wk:adogit>verbindung:projekt:repo}} auf eine Seite innerhalb eines DWDO-Projekts setzt (hier unterhalb von {lang}:projects:). Wer den Mount registriert und danach nichts sieht, hat diesen zweiten Schritt vor sich, keinen Fehler.

Sichtbarkeits-Tier und DokuWiki-ACL

Der Tier eines Mounts ist die einzige Bedienstelle für die Sichtbarkeit. Die ACL wird je Request frisch gelesen, ein Tier-Wechsel wirkt daher sofort. Regeln entstehen auf dem Namespace und auf namespace:*; Administratoren dürfen per Superuser immer.

Tier	@ALL (anonym)	@user (angemeldet)	@wvds (Entwickler)	@wvdse (Editoren)	Projekt-Rollengruppen
`private`	0	–	–	8	–
`readonly`	0	2	2	8	–
`showcase`	1	–	–	8	–
`library`	1	2	–	8	–
`public`	2	–	–	8	–
`team`	0	–	–	8	`readers` 1, `contributors` 2, `maintainers` 8

Die Rollengruppen des Tiers team tragen den roleprefix aus wkdocore und den Projektschlüssel, zum Beispiel @dwdo_dwplugins_maintainers.

Die Stufen showcase und library trennen zwei Rechte, die public gemeinsam vergibt: im Browser ansehen und eine Kopie beziehen. Bei showcase darf jeder lesen und niemand klonen; bei library darf jeder lesen und jedes angemeldete Konto klonen. Die Trennlinie ist die Anmeldung, nicht das Publikum — wer eine Kopie nimmt, ist damit ein Konto, das sich später benennen lässt.

Eine Zahl, zwei Lesarten

Die geschriebene Zahl ist zugleich DokuWiki-Recht und Fähigkeit dieses Pakets.

Level	In diesem Plugin	In DokuWiki
1	Browsen und Rendern im Wiki	Seite lesen
2	`clone`, `fetch` und ZIP-Download	bestehende Seite bearbeiten
4	`push` nach `refs/heads/users/<login>/`	Seite anlegen
8	`push` ohne Einschränkung sowie Bearbeiten und Commit aus dem Wiki	Datei hochladen

Die zweite Spalte ist der Grund, warum ein Mount auf einem Namespace mit echten Wiki-Seiten nicht harmlos ist: public öffnet dort den Seiteneditor für anonyme Besucher. Die Vorschau im Assistenten zählt deshalb die bereits vorhandenen Seiten.

Die Regeln stehen in einem verwalteten Block in conf/acl.auth.php, zwischen den Zeilen # BEGIN wkdoadogit-managed und # END wkdoadogit-managed. Diesen Block nicht von Hand bearbeiten — stattdessen den Tier des Mounts setzen. Der Schreiber ersetzt ausschließlich diesen Block (atomar, mit Temporärdatei, Umbenennen und Sperre) und lässt alle anderen Regeln unangetastet, auch von Hand oder über den Kern-Admin acl gepflegte. Ein entfernter Mount verliert seine Regeln; der Namespace fällt dann auf die Site-Vorgabe zurück.

Zweiter Faktor: zwei Kategorien, zwei Stufen

Ist Identity installiert, verlangt die Brücke do=wkdoadogit_stepup einen Nachweis.

Kategorie	Anforderung	Gilt für
`mount-admin`	`MFA_ANY`	Mounts anlegen, ändern und entfernen sowie Subversion-Verbindungen registrieren
`token-issue`	`AUTHENTICATED`, von der Installation anhebbar	ein persönliches Token ausstellen

Die beiden Stufen sind verschieden, weil die Handlungen es sind: ein Mount entscheidet, wer welches Repository sieht, ein persönliches Token betrifft nur das eigene Konto und wird im Alltag mehrfach gebraucht.

Die Prüfung tritt zusätzlich zur DokuWiki-ACL hinzu, nie an ihre Stelle. Ohne wkidentity verhält sich das Paket unverändert. Der git-Proxy unterliegt ihr nicht: er läuft ohne Session und kann keine interaktive Rückfrage führen, weshalb die Anforderung an der Ausstellung des Tokens hängt und nicht an jedem Request, den es später trägt.

Grenzen und Hinweise

Mount-Registrierung und ACL-Schreiben sind Administratoren vorbehalten; persönliche Token sind Selbstbedienung.
Keine feingranulare ACL je Unterordner — der Tier gilt mount-weit.
Anlegen ist möglich, Hochladen nicht. Der Arbeitsbereich legt eine neue Textdatei an (Schaltfläche Neue Datei, ab Schreibrecht); ein Dateiauswahldialog fehlt bewusst. Die Push-Schnittstelle nimmt base64-kodierte Inhalte entgegen, aber ein Bild über ein Textfeld einzureichen wäre eine Zusage, die diese Oberfläche nicht halten kann. Binärdateien gehen über einen Git-Client zurück. Siehe Eine neue Datei im Browser anlegen.
Anlegen überschreibt nie. Liegt unter dem Pfad bereits eine Datei, antwortet der Server mit conflict und schreibt nichts — dieselbe Regel wie bei einem vergebenen Branch-Namen. Der Weg über plugin_wkdoadogit_commit mit leerer Basiskennung würde die Datei still ersetzen; deshalb hat das Anlegen einen eigenen Aufruf und nicht ein Zusatzfeld.
Kein Reiter Commits. Die Historie wird nicht angeboten, weil sie nicht umgesetzt ist. Ein Reiter, der sie verspricht, wäre derselbe Fehler wie die früher ausgegrauten Reiter.
Das Umschalten zwischen Branches und Tags ist umgesetzt; die frühere Angabe, die Reiter seien inaktiv, gilt nicht mehr — siehe Technische Referenz: Branches und Tags.
Ausgehende HTTPS-Verbindungen brauchen ein CA-Bündel in der php.ini (curl.cainfo). Fehlt es, scheitert jeder Aufruf an das Quellsystem im TLS-Handshake, und weil sämtliche REST-Aufrufe weich abfallen, sieht das Ergebnis exakt aus wie ein Projekt ohne Repositories.
Die Marke {{wk:adogit>…}} wirkt nicht außerhalb der Projektwurzel, weil die Verbindung über das DWDO-Projekt der Seite aufgelöst wird. {{source>ado:…}} hat zusätzlich den Weg über den Mount-Namespace.
Jede Einbettung ist ein Netzaufruf, begrenzt durch Zeitschranken und Byte-Obergrenze in wkdoado.
Der git-Proxy meldet sich bei ADO stets mit einem Service-PAT an; pushedBy ist dort der Service-Account, der Commit-Author bleibt der Wiki-Benutzer.
max_execution_time steht in server/php/php.ini auf 30 Sekunden: für die geprüften Repository-Größen unkritisch, bei sehr großen Repositorys die nächste Grenze.
Eine Ablehnung ist bewusst wortkarg: nicht gemountetes Repository, unbekannte Verbindung und fehlendes Recht sind von außen kaum zu unterscheiden.
Verbindliche Quelle der Level-Zuordnung ist Domain/MountAclWriter::TIERS. Bei Änderungen diese Seite und die Plugin-README mitpflegen.