Technische Referenz

Nachschlagewerk zu wkdoadogit: die Mount-Verwaltung, die Auszeichnungen, jede Aktion mit ihrer Adresse, die persönlichen Zugriffs-Token und jede Einstellung. Warum die Dinge so gebaut sind, steht in den Konzepten; was Sie tun wollen, auf ADO-Git.

Paket: wkdoadogit · Ablage: lib/plugins/wkdoadogit/
Autor: Wolfgang van der Stille Wolfgang.van.der.Stille@gmail.com (The White Knight Labs) · Lizenz: GPL 2.0-only

Mounts verwalten

Der Bildschirm liegt unter /doku.php?do=admin&page=wkdoadogit_mounts, im Menü unter Administration > Repository-Mounts. Er ist Administratoren vorbehalten, da hier die Site-ACL geschrieben wird.

Registrieren läuft in einem Assistenten mit vier Bildschirmen: Verbindung, Projekt, Repositorys (mit Namespace-Vorlage und Sichtbarkeitsstufe) und Vorschau. Projekt und Repositorys liest die Verbindung; ein Freitextfeld erscheint nur, wenn der Server nicht antwortet.
Vorschau ist der einzige Bildschirm, der schreibt. Er zeigt jede ACL-Zeile, die entsteht, und warnt, wenn der Namespace bereits Wiki-Seiten trägt.
Sichtbarkeitsstufe oder Namespace ändern: im Zeilenmenü des Mounts das Namespace-Feld und die Auswahl der Sichtbarkeitsstufe anpassen, dann Speichern. Beides ändert sich in einem Schritt, und die alten Regeln fallen erst nach dem erfolgreichen Umzug weg.
Entfernen: im Zeilenmenü Entfernen.
Das Zeilenmenü liefert außerdem die Clone-Adresse je Sprache und die fertigen Marken für die Anzeige auf einer Wiki-Seite.

Jede Handlung schreibt zuerst den Mount, dann die ACL.

Syntax

Marke	Aufbau	Was sie darstellt	Wo sie wirkt
`{{wk:adogit>…}}`	`verbindung:projekt:repo[:ref[:pfad]]`, optionaler Zusatz `region=<name>`	Baum aus Ordnern und Dateien	nur auf einer Seite unterhalb der Projektwurzel
`{{source>ado:…}}`	`verbindung:projekt:repo:ref:pfad`, optionaler Zusatz `#L10-L40`	Inhalt einer einzelnen Datei	auf einer Seite unterhalb der Projektwurzel oder innerhalb des Mount-Namespace

Das erste Feld ist der Schlüssel der Verbindung, nicht ihre Nummer; gesucht wird sie innerhalb des DWDO-Projekts, zu dem die Seite gehört. Bei {{wk:adogit>…}} bedeutet ein fehlender Ref den Standardbranch und ein fehlender Pfad die Wurzel. Bei {{source>ado:…}} sind alle fünf Felder Pflicht.

Die Marke {{source>ado:…}} braucht wksourceview. Ohne dieses Plugin ist das Schema ado nicht registriert und die Darstellung meldet, dass die Quelle nicht verfügbar ist. Einzelheiten und Darstellungsoptionen stehen in Quellcode auf einer Wiki-Seite anzeigen.

Aktionen und Einstiegspunkte

Adresse	Wer	Zweck
`do=admin&page=wkdoadogit_mounts`	Administrator	Mounts und ihre Sichtbarkeitsstufen
`do=admin&page=wkdoadogit`	Manager	Zugriffs-Token aller Benutzer
`do=wkdoadogit_tokens`	jeder Angemeldete	eigene Zugriffs-Token
`do=wkdoadogit_repo&ns=<mount>`	ACL-Stufe 1 oder höher	eigener Bildschirm für ein eingebundenes Repository: Dateibaum, Branches, Tags, Bezugswege
`do=wkdoadogit_archive&ns=…&ref=…`	ACL-Stufe 2 oder höher	Momentaufnahme als ZIP herunterladen
`do=wkdoadogit_diag`	–	Tabelle der aufgelösten Dienste
`do=wkdoadogit_stepup`	–	Brücke für den Nachweis des zweiten Faktors
`lib/plugins/wkdoadogit/git.php/<mount-pfad>`	git-Client	Proxy für `clone`, `pull` und `push`

Verbindungen werden nicht hier gepflegt, sondern in wkdoado, auf einer Projektseite mit der Aktion do=wkdoado.

Jedes Repository hat eine Adresse

do=wkdoadogit_repo ist die Antwort auf ein Grundproblem: Eine Einbindung ist keine Wiki-Seite. Von 61 eingebundenen Repositories hatten 52 keine Seite, auf der die Marke {{wk:adogit>…}} stand, und waren damit im Wiki schlicht nicht ansprechbar – sie existierten in der Verwaltung und nirgends sonst.

Die Aktion braucht keine vorbereitete Seite. Sie nimmt den Einhängenamensraum entgegen, sucht die Einbindung, holt sich das Projekt aus dem gefundenen Datensatz (nicht aus der Seitenkennung, die hier nichts über das Projekt aussagt) und prüft die ACL des Einhängenamensraums wie jeder andere Zugang auch. Wer nicht lesen darf, bekommt keine leere Seite, sondern die Feststellung und einen Weg weiter: eine Zugangsanfrage für Angemeldete, eine Anmeldung für alle anderen.

Der Bildschirm zeigt Projekt, Repository, Sichtbarkeit, die eigene Rolle und den dargestellten Stand, darunter die Bereichswahl und die Reiter Code, Commits, Branches und Tags. Commits erscheint nur, wenn das Quellsystem einen Verlauf liefern kann; bei Azure DevOps ist das der Fall.

Bereichswahl: Repository und Branch

Der Wechsel zu einem anderen Repository desselben Projekts ist die häufigste Bewegung innerhalb eines Projekts; er geht deshalb ohne Umweg über die Liste. Über den Reitern stehen zwei Auswahlfelder: das eine für die Repositories desselben Projekts, das andere für die Branches des gezeigten Repositorys.

Was in der Repository-Auswahl steht, ist geprüft. Jede Einbindung des Projekts läuft einzeln

durch dieselbe Sichtbarkeitsprüfung wie in der Liste. Was das Konto nicht sehen darf, fehlt –

  nicht ausgegraut, sondern abwesend: ein Name in einer Auswahl ist die Aussage, dass es die Sache
  gibt.
* **Eine Auswahl mit einem einzigen Eintrag wird nicht gezeichnet.** Sie könnte nichts bewirken.
* **Zwei getrennte Formulare, nicht eines.** Sonst würde ein Repositorywechsel den Branch des alten
  Repositorys mitschicken, und das Ergebnis wäre eine Fehlermeldung über einen Stand, den niemand
  angefordert hat.
* **Ohne Skript bedienbar.** Beides sind gewöhnliche Formulare mit Absendeknopf; das Ergebnis ist
  eine Adresse, die sich als Lesezeichen speichern lässt.
* **Bei mehr als 200 Branches** tritt an die Stelle der Auswahl ein Verweis auf den Reiter
  //Branches//. Eine gekürzte Auswahl würde genau den Branch verschweigen, den jemand sucht.

Commits

Der Reiter Commits zeigt die jüngsten Commits des dargestellten Stands – desselben, den die Branch-Auswahl darüber nennt; über der Tabelle steht, wessen Verlauf es ist. Jede Zeile nennt die Kurzform des Commits (der vollständige Wert steht im Titel), die erste Zeile der Nachricht, den Autor und den Zeitpunkt. Hat die Nachricht weitere Zeilen, steht dahinter die Marke mehr; hat ein anderer als der Autor den Commit übernommen, steht das unter dem Namen.

Wie viele Commits erscheinen, legt commits_shown fest (Vorgabe 30, höchstens 100).
Keine Blätterfunktion. Der Reiter beantwortet, was hier zuletzt geschah; die vollständige

Historie gehört in einen Git-Client.

Eine Commit-Kennung ist Text zum Zitieren, kein Verweis. Eine Ansicht für einzelne

Änderungen hat der Arbeitsbereich nicht, und ein Verweis, der auf einer Ablehnung landet,

  wäre eine falsche Zusage.
* **Lässt sich kein Verlauf lesen**, sagt der Reiter das, statt eine leere Tabelle zu zeigen.

Branches und Tags

Die Reiter Branches und Tags führen zu Listen.

Jede Zeile nennt den Namen und die Kurzform des Commits, der vollständige Wert steht im Titel. Standardbranch und der gerade dargestellte Stand sind markiert. Ein Klick kehrt zum Reiter Code zurück, festgelegt auf diesen Stand – der in der Adresse steht, sodass ein Link auf einen bestimmten Branch gültig bleibt.

Ein Repository ohne Tags zeigt den Satz, dass es keine hat. Das ist ein Zustand, kein Fehler, und unterscheidet sich von „nicht erreichbar“.

In der eingebetteten Ansicht ({{wk:adogit>…}}) führen dieselben Reiter auf diesen Bildschirm statt eine Liste in die Seitenspalte zu zwängen: Diese Ansicht ist häufig 15em breit, eine Ref-Liste ist es nicht.

Beitrag zum Repository-Explorer

Das Paket trägt seine Einbindungen als Repository-Quelle in das Verzeichnis von wkdocore ein und erscheint dadurch in der projektübergreifenden Übersicht. Die Projektoberfläche kennt dieses Paket nicht; sie fragt das Verzeichnis, und das Verzeichnis fragt seine angemeldeten Quellen.

Die Quelle filtert selbst: Eine Zeile entsteht nur, wenn das Konto die Einbindung sehen darf, und die vier gemeldeten Fähigkeiten – ansehen, beziehen, vorschlagen, schreiben – sind die der Sichtbarkeitsstufe, nicht eine Vermutung. Standardbranch, Sprache und letzte Änderung bleiben offen: Sie zu füllen hieße, je Zeile das Quellsystem zu fragen.

Persönliche Zugriffs-Token

Externe git-Clients melden sich am Proxy als DokuWiki-Benutzer an, und zwar mit einem persönlichen Token; das Wiki-Passwort gehört nicht in den git-Client. Jeder angemeldete Benutzer verwaltet seine Token unter /doku.php?do=wkdoadogit_tokens, Administratoren zusätzlich im Menü ADO-Git access tokens. Gespeichert wird nur ein gehashter Wert; der Klartext erscheint genau einmal, bei der Ausstellung. Jedes Token beginnt mit dem Präfix wkg_.

Für clone ist ACL-Stufe 2 nötig, für push ACL-Stufe 4. Bei den ACL-Stufen 4 bis 7 sind nur Branches unterhalb von refs/heads/users/<login>/ erlaubt. Das Vorgehen beschreibt Ein gemountetes Repository klonen.

Konfiguration

Schlüssel	Vorgabe	Wirkung
`mount_languages`	`de,en,hr,it,sl`	Sprachsegmente, in die ein Mount mit dem Platzhalter `{lang}` expandiert; auf dieser Instanz `de,en,sl`
`repofactsttl`	`3600`	Sekunden, die der Repository-Explorer den Standardbranch aus einer Antwort des Quellsystems weiterverwendet; eine Abfrage beantwortet ein ganzes ADO-Projekt. `0` schaltet die Abfrage ab, die Spalte entfällt dann.
`repofactsfailttl`	`300`	Sekunden, die eine fehlgeschlagene Abfrage gemerkt wird – ein nicht erreichbares Quellsystem wird einmal je Zeitfenster gefragt, nicht bei jedem Seitenaufruf
`commits_shown`	`30`	Anzahl der Commits im Reiter Commits (1 bis 100)

Weitere Einstellungen hat das Paket bewusst nicht: die Verbindung kommt aus wkdoado, die Rechte aus DokuWiki, die Mounts aus dem Speicher.

Technische Notizen (für Betreiber und Entwickler): Inbetriebnahme des git-Proxys auf dem portablen Stack · Herkunft der Sichtbarkeitsstufen bei der Mount-Registrierung.

Weiterführend: die Datei README im Repository wkdoadogit; die Paketübersicht steht in der DWE-Übersicht.

Baut auf: wkcore (Dienstregistry) · wkdocore (Projekt und Rollen) · wkdostorage (Mounts und Token) · wkdoado (ADO-Verbindung) · wksourceview (Quelltext und Schublade) · wkfluentui (Bausteine und Dokumentenkopf).

Nicht zu verwechseln mit wkdogit, das lokale Repositorys über ein git-Binary bedient, streng lesend.