Ein ADO-Repository erstmals im Wiki anzeigen

Diese Anleitung führt ein Repository aus Azure DevOps von null bis zur sichtbaren Datei auf einer Wiki-Seite. Sieben Abschnitte folgen der Reihenfolge, in der Sie arbeiten; der letzte ist optional.

Die Werte in den Beispielen stammen aus dieser Installation. Ersetzen Sie sie durch Ihre eigenen.

Was	Wert in diesem Beispiel
Schlüssel des DWDO-Projekts	`dwplugins`
Namespace des Projekts	`de:projects:dwplugins`
Schlüssel der Verbindung	`wvds`
Basisadresse des ADO-Servers	`https://devops.wvds.it/Me`
Projekt in Azure DevOps	`DokuWiki-Plugins`
Repository	`wkdoadogit`
Namespace des Mounts	`code:dokuwiki-plugins:wkdoadogit`

Voraussetzungen

Für die Verbindung brauchen Sie die Rolle manage im DWDO-Projekt. Die Liste der Verbindungen darf auch ein Leser sehen, anlegen kann er sie nicht.
Für den Mount brauchen Sie Administratorrechte, denn ein Mount schreibt Rechte für die ganze Site.
Installiert und aktiviert sein müssen wkcore, wkdocore, wkdostorage, wkdoado und wkdoadogit. Ohne wksourceview öffnen Dateien nicht in der Schublade.
Das DWDO-Projekt muss zweimal vorhanden sein: als Namespace unterhalb der Projektwurzel (hier {lang}:projects:) und als Datensatz im DWDO-Speicher. Ohne den Datensatz lässt sich die Verbindung nicht speichern.
In den Einstellungen von wkdoado muss der Name des ADO-Servers in ado_host_allow stehen. Eine leere Liste weist jeden Aufruf ab.
Das Secret (PAT) muss außerhalb der Datenbank liegen, als Verweis vault:, file:, env: oder enc:.
Auf dem Server muss die PHP-Erweiterung curl verfügbar sein. Ohne sie lädt der Browser nicht und der git-Proxy bricht ab.

Legen Sie vor dem ersten Mount eine Sicherung von conf/acl.auth.php an: ein Mount schreibt hinein. Dieses Wiki erlaubt site-weit * @ALL 1, ein Mount ist also erst geschützt, sobald sein Tier die Regeln geschrieben hat — private setzt @ALL 0.

Verbindung zu Azure DevOps

Die Verbindung beschreibt den ADO-Server und gehört zu genau einem DWDO-Projekt. Sie wird nicht in der Administration eingerichtet, sondern auf einer Projektseite.

Öffnen Sie eine beliebige Projektseite und hängen Sie die Aktion do=wkdoado an, zum Beispiel /doku.php?id=de:projects:dwplugins:start&do=wkdoado. Denselben Bildschirm öffnet die Befehlspalette mit dem Eintrag ADO-Verbindungen verwalten.
Steht die Verbindung schon in der Liste, notieren Sie ihren Schlüssel und gehen Sie zum nächsten Abschnitt.
Füllen Sie das Formular für eine neue Verbindung aus: Schlüssel (wvds; erlaubte Zeichen [A-Za-z0-9_-], höchstens 64), Titel, Deployment (services für den Dienst dev.azure.com oder server für eine eigene Installation), Basis-URL, bei Bedarf Organisation (services) und Collection (server) sowie API-Version (Vorgabe 7.0).
Wählen Sie Anlegen.
Wählen Sie in der Zeile der Verbindung den Secret-Modus (vault:, file:, env: oder enc:), tragen Sie den Wert ein und speichern Sie. Beim Modus vault: ist der Wert die Kennung eines Eintrags in wkvault, in dieser Installation adogit-service-pat.
Wählen Sie Testen und warten Sie das Ergebnis ab. Der Test unterscheidet vier Ursachen: verbotener Server, unerreichbares Ziel, Zertifikatsfehler und Anmeldefehler.

Fahren Sie erst fort, wenn der Test erfolgreich ist.

Beim Deployment server ist die Collection bereits Teil der Basisadresse (https://devops.wvds.it/Me). Füllen Sie zusätzlich das Feld Collection (server), wird die Collection ein zweites Mal angehängt und jeder REST-Aufruf endet mit HTTP 404. Nennen Sie die Collection nur an einer Stelle.

Repository mounten

Der Mount bindet das Repository an einen Wiki-Namespace und schreibt die Rechte dafür.

Öffnen Sie Administration > ADO-Git Repo-Mounts, direkt /doku.php?do=admin&page=wkdoadogit_mounts.
Klappen Sie Mount registrieren auf.
Wählen Sie auf dem Bildschirm 1. Verbindung die Verbindung. In der Liste steht sie als projekt / schlüssel, zum Beispiel dwplugins / wvds. Wählen Sie Weiter.
Wählen Sie auf dem Bildschirm 2. ADO-Projekt das Projekt, zum Beispiel DokuWiki-Plugins. Die Liste liest die Verbindung; antwortet der Server nicht, sagt der Bildschirm das und bietet ein Freitextfeld.
Markieren Sie auf dem Bildschirm 3. Repositorys ein oder mehrere Repositorys, zum Beispiel wkdoadogit. Passen Sie bei Bedarf das Feld Namespace-Vorlage an, wählen Sie den Sichtbarkeits-Tier und dann Vorschau.
Lesen Sie den Bildschirm 4. Vorschau. Er zeigt, was der Tier gewährt, welcher Namespace entsteht und jede Rechtezeile, die geschrieben wird. Er warnt auch, wenn der Namespace bereits Wiki-Seiten trägt.
Wählen Sie Registrieren.

Zuerst wird der Mount geschrieben, dann die Rechte. Scheitert das Schreiben der Rechte, sagt der Bildschirm es Ihnen; einen stillen Zwischenzustand gibt es nicht.

Die Namespace-Vorlage lautet standardmäßig code:{project}:{repo}. Die Platzhalter {project} und {repo} werden durch die Namen aus Azure DevOps ersetzt, ein etwaiges {lang} bleibt stehen und expandiert erst beim Schreiben der Rechte je Sprache.

Sichtbarkeits-Tier

Der Tier ist die einzige Stelle, an der die Sichtbarkeit geregelt wird. Die Rechte werden bei jedem Request frisch gelesen, ein Wechsel wirkt daher sofort.

Tier	Wer wie viel bekommt	Was das bedeutet
`private`	`@ALL` 0, `@wvdse` 8	sichtbar nur für Editoren und Administratoren
`readonly`	`@ALL` 0, `@user` 2, `@wvds` 2, `@wvdse` 8	Angemeldete lesen und klonen, Anonyme sehen nichts
`public`	`@ALL` 2, `@wvdse` 8	jeder liest und klont
`team`	`@ALL` 0, Projekt-Rollengruppen (`readers` 1, `contributors` 2, `maintainers` 8), `@wvdse` 8	sichtbar nur für das Team dieses Projekts

Was die einzelne Zahl im Wiki und was sie in diesem Plugin bedeutet, erklärt die technische Referenz.

Der Tier public gewährt der Gruppe @ALL den Grad 2. Dieselbe Zahl liest DokuWiki als Recht, eine bestehende Seite zu bearbeiten. Auf einem leeren Namespace ist das belanglos, auf einem Namespace mit Wiki-Seiten öffnet es den Editor für alle Besucher.

Die Rechte liegen in einem verwalteten Block der Datei conf/acl.auth.php, zwischen den Zeilen # BEGIN wkdoadogit-managed und # END wkdoadogit-managed. Diesen Block nicht von Hand bearbeiten – setzen Sie stattdessen den Tier des Mounts.

Mount-Namespace

Nach der Registrierung steht das Repository mit seinem Namespace in der Mount-Liste:

code:dokuwiki-plugins:wkdoadogit

Die Spalte Regeln sagt, ob die geschriebenen Rechte zum Tier passen (written), fehlen (NOT written) oder abweichen. Beim Tier public entstehen in conf/acl.auth.php vier Zeilen:

# mount: code:dokuwiki-plugins:wkdoadogit (public)
code:dokuwiki-plugins:wkdoadogit	@ALL	2
code:dokuwiki-plugins:wkdoadogit:*	@ALL	2
code:dokuwiki-plugins:wkdoadogit	@wvdse	8
code:dokuwiki-plugins:wkdoadogit:*	@wvdse	8

Der Mount-Namespace ist virtuell. Er trägt Rechte, aber keine Seiten, und der Mount legt auch keine an. Öffnen Sie /doku.php?id=code:dokuwiki-plugins:wkdoadogit, sehen Sie eine leere Seite. Das ist kein Fehler – das Repository zeigt erst der nächste Abschnitt.

Seite mit dem Repository-Browser

Ein Repository wird dort gezeichnet, wo ein Autor die Marke setzt. Sie wirkt allein auf einer Seite innerhalb des DWDO-Projekts, weil der Browser die Verbindung über das Projekt dieser Seite sucht.

Öffnen Sie die Seite repos Ihres Projekts im Editor: /doku.php?id=de:projects:dwplugins:repos&do=edit.
Setzen Sie die Marke {{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit}} ein.
Speichern Sie die Seite.

Jetzt erscheinen der Kopf mit Repository-Name, Tier-Abzeichen und Branch-Name sowie der Baum des Wurzelordners.

Der Aufbau der Marke lautet {{wk:adogit>verbindung:projekt:repo[:ref[:pfad]]}}:

Feld	Bedeutung	Wenn Sie es weglassen
`verbindung`	Schlüssel der Verbindung (`wvds`), nicht ihre Nummer	ist Pflicht
`projekt`	Name des Projekts in Azure DevOps	ist Pflicht
`repo`	Name des Repositorys	ist Pflicht
`ref`	Branch, Tag oder Commit	gilt der Standardbranch des Repositorys
`pfad`	Ordner, aus dem der Baum ausgeht	gilt die Wurzel des Repositorys

Um den Browser in eine Seitenregion der Shell zu stellen, hängen Sie region=toc an: {{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit region=toc}}.

Die Reiter Branches und Tags im Kopf sind sichtbar, aber inaktiv. Den dargestellten Branch wählen Sie in der Marke, nicht in der Oberfläche.

Die fertige Marke bietet auch die Mount-Liste an: öffnen Sie im Zeilenmenü des Mounts den Eintrag Dieses Repository auf einer Wiki-Seite anzeigen. Dort stehen beide Marken mit bereits eingesetzten Werten.

Ordner und Datei öffnen

Einen Ordner im Baum öffnen Sie, indem Sie ihn auswählen. Der Inhalt lädt erst beim Öffnen, und das Recht wird dabei erneut geprüft; der Baum kommt deshalb nie aus dem gemeinsamen Seiten-Cache.

Den Ordner können Sie auch vorab festlegen, über das fünfte Feld der Marke:

{{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain}}

Eine Datei öffnen Sie, indem Sie sie auswählen. Es erscheint die Schublade von wksourceview, und die Datei wird mit Syntaxhervorhebung gezeichnet. Ohne dieses Plugin gibt es keine Schublade, der Baum bleibt.

Wer Schreibrecht hat, findet neben jeder Datei eine Schaltfläche zum Bearbeiten und im Kopf die Schaltfläche Neuer Branch/Tag. Das Vorgehen beschreibt eine Datei bearbeiten und committen.

Über dem Baum liegt die aufklappbare Fläche Dieses Repository beziehen mit der Adresse für clone, dem ZIP-Download und dem Link zu den persönlichen Token. Sie erscheint nur für Level 2 oder mehr; siehe Repository klonen.

Quellcode einbetten

Dieser Abschnitt ist optional. Eine einzelne Datei können Sie auch unmittelbar auf der Seite zeichnen, ohne Browser:

{{source>ado:wvds:DokuWiki-Plugins:wkdoadogit:main:/Domain/MountAclGate.php#L141-L146}}

Den Unterschied zwischen beiden Marken, die Darstellungsoptionen und die Grenzen beschreibt Quellcode auf einer Wiki-Seite anzeigen.

Erwartetes Ergebnis

Die Seite de:projects:dwplugins:repos zeigt den Kopf des Repositorys wkdoadogit mit Tier-Abzeichen und Branch-Namen.
Ordner lassen sich öffnen, Dateien erscheinen in der Quellcode-Schublade.
Ein Leser ohne Leserecht auf code:dokuwiki-plugins:wkdoadogit sieht auf derselben Seite weder Baum noch Repository-Namen, sondern nur eine Zustandskarte.
In conf/acl.auth.php stehen vier Zeilen dieses Mounts innerhalb des verwalteten Blocks.

Wann kein persönliches Token nötig ist

Das persönliche Token ist ein Token für git-Clients, nicht für das Wiki. Innerhalb des Wikis wird es nie gebraucht.

Handlung	Persönliches Token	Was stattdessen gilt
im Baum browsen	nein	Leserecht (Level 1 oder mehr) auf dem Mount-Namespace
Datei öffnen und Einbettung mit `{{source>ado:…}}`	nein	dasselbe Leserecht
Bearbeiten und Committen aus dem Wiki	nein	Schreibrecht (Level 8) auf dem Mount-Namespace
ZIP-Download	nein	Level 2 oder mehr
`git clone` oder `git pull` außerhalb des Wikis	ja	Level 2 oder mehr und ein gültiges Token
`git push` außerhalb des Wikis	ja	Level 4 oder mehr und ein gültiges Token

Bei Azure DevOps meldet sich in allen Fällen der Service-Account an. Das persönliche Token sagt nur, wer im Wiki fragt.

Wenn etwas nicht funktioniert

Was Sie sehen	Wahrscheinlichste Ursache
„Dieses Repository ist mit diesem Wiki nicht verbunden.„	die Marke nennt einen falschen Verbindungsschlüssel, einen falschen Projekt- oder Repository-Namen — oder der Mount ist nicht registriert
„Sie haben kein Leserecht auf dieses Repository.“	der Mount existiert, der Tier erfasst Sie nicht
„Der ADO-Quellendienst ist nicht verfügbar.„	Verbindung, Liste der erlaubten Server, Secret oder fehlendes `curl`
„Das Repository konnte nicht geladen werden.“	die Marke ließ sich nicht zerlegen oder der genannte Branch existiert nicht
die Seite zeigt den Markentext im Klartext	die Seite liegt außerhalb der Projektwurzel oder das Plugin ist nicht aktiviert

Die ausführliche Diagnose mit Vorgehen steht in der Diagnose.

Nächste Schritte

Quellcode auf einer Wiki-Seite anzeigen – Quellcode auf einer Wiki-Seite anzeigen
Eine Datei aus dem Wiki bearbeiten und committen – eine Datei aus dem Wiki bearbeiten und committen
Ein gemountetes Repository klonen – clone, pull und push sowie das persönliche Token
Konzepte – Sichtbarkeits-Tier, Rechte und Grenzen