Mostrare per la prima volta un repository ADO nel wiki

Questa guida porta un repository di Azure DevOps da zero fino a un file visibile su una pagina wiki. Sette sezioni seguono l'ordine in cui si lavora; l'ultima è facoltativa.

I valori degli esempi provengono da questa installazione. Sostituiteli con i vostri.

Che cosa	Valore in questo esempio
chiave del progetto DWDO	`dwplugins`
spazio dei nomi del progetto	`it:projects:dwplugins`
chiave della connessione	`wvds`
indirizzo base del server ADO	`https://devops.wvds.it/Me`
progetto in Azure DevOps	`DokuWiki-Plugins`
repository	`wkdoadogit`
spazio dei nomi del mount	`code:dokuwiki-plugins:wkdoadogit`

Prerequisiti

Per la connessione serve il ruolo manage nel progetto DWDO. L'elenco delle connessioni può vederlo anche un lettore, ma non può crearne una.
Per il mount servono i diritti di amministratore, perché un mount scrive permessi validi per l'intero sito.
Devono essere installati e attivi i plugin wkcore, wkdocore, wkdostorage, wkdoado e wkdoadogit. Senza wksourceview i file non si aprono nel cassetto.
Il progetto DWDO deve esistere due volte: come spazio dei nomi sotto la radice dei progetti (qui {lang}:projects:) e come record nell'archivio DWDO. Senza quel record la connessione non si salva.
Nelle impostazioni di wkdoado il nome del server ADO deve comparire in ado_host_allow. Un elenco vuoto rifiuta ogni chiamata.
Il segreto (PAT) deve trovarsi fuori dalla banca dati, come riferimento vault:, file:, env: o enc:.
Sul server deve essere disponibile l'estensione PHP curl. Senza di essa il browser non si carica e il proxy git si interrompe.

Prima del primo mount fate una copia di sicurezza del file conf/acl.auth.php: un mount vi scrive dentro. Questo wiki consente * @ALL 1 per l'intero sito, quindi un mount è protetto solo quando il suo livello ha scritto le regole — private imposta @ALL 0.

Connessione ad Azure DevOps

La connessione descrive il server ADO e appartiene a un solo progetto DWDO. Non si imposta nell'amministrazione, bensì su una pagina di progetto.

Aprite una qualsiasi pagina del progetto e aggiungete l'azione do=wkdoado, per esempio /doku.php?id=it:projects:dwplugins:start&do=wkdoado. La stessa schermata si apre dalla tavolozza dei comandi con la voce Gestisci le connessioni ADO.
Se la connessione è già nell'elenco, annotate la sua chiave e passate alla sezione successiva.
Compilate il modulo per una nuova connessione: Chiave (wvds; caratteri ammessi [A-Za-z0-9_-], al massimo 64), Titolo, Distribuzione (services per il servizio dev.azure.com oppure server per un'installazione propria), URL di base, se necessario Organizzazione (services) e Collection (server), e Versione API (predefinito 7.0).
Scegliete Aggiungi.
Nella riga della connessione scegliete la modalità del segreto (vault:, file:, env: o enc:), inserite il valore e salvate. Nella modalità vault: il valore è l'identificativo di una voce in wkvault, in questa installazione adogit-service-pat.
Scegliete Prova e attendete l'esito. La prova distingue quattro cause: server vietato, destinazione irraggiungibile, errore del certificato ed errore di autenticazione.

Proseguite solo quando la prova riesce.

Con la distribuzione server la collection fa già parte dell'indirizzo base (https://devops.wvds.it/Me). Se compilate anche il campo Collection (server), la collection viene aggiunta una seconda volta e ogni chiamata REST termina con l'errore HTTP 404. Indicate la collection in un solo punto.

Montaggio del repository

Il mount lega il repository a uno spazio dei nomi del wiki e ne scrive i permessi.

Aprite Amministrazione > Mount dei repository ADO-Git, direttamente /doku.php?do=admin&page=wkdoadogit_mounts.
Espandete Registra un mount.
Nella schermata 1. Connessione scegliete la connessione. Nell'elenco compare come progetto / chiave, per esempio dwplugins / wvds. Scegliete Avanti.
Nella schermata 2. Progetto ADO scegliete il progetto, per esempio DokuWiki-Plugins. L'elenco proviene dalla connessione; se il server non risponde, la schermata lo dichiara e offre un campo libero.
Nella schermata 3. Repository contrassegnate uno o più repository, per esempio wkdoadogit. Se occorre adattate il campo Modello di spazio dei nomi, scegliete il livello di visibilità e poi Anteprima.
Leggete la schermata 4. Anteprima. Mostra che cosa concede il livello, quale spazio dei nomi nascerà e ogni riga di permesso che verrà scritta. Avverte anche se lo spazio dei nomi contiene già pagine wiki.
Scegliete Registra.

Prima viene scritto il mount, poi i permessi. Se la scrittura dei permessi non riesce, la schermata ve lo comunica; non esiste uno stato intermedio silenzioso.

Il modello di spazio dei nomi è per impostazione predefinita code:{project}:{repo}. I segnaposto {project} e {repo} vengono sostituiti con i nomi provenienti da Azure DevOps, mentre un eventuale {lang} resta e si espande per lingua solo alla scrittura dei permessi.

Livello di visibilità

Il livello è l'unico punto in cui si regola la visibilità. I permessi si leggono a ogni richiesta, perciò un cambiamento ha effetto immediato.

Livello	Chi riceve quanto	Che cosa significa
`private`	`@ALL` 0, `@wvdse` 8	visibile solo a redattori e amministratori
`readonly`	`@ALL` 0, `@user` 2, `@wvds` 2, `@wvdse` 8	gli utenti autenticati leggono e clonano, gli anonimi non vedono nulla
`public`	`@ALL` 2, `@wvdse` 8	chiunque legge e clona
`team`	`@ALL` 0, gruppi di ruolo del progetto (`readers` 1, `contributors` 2, `maintainers` 8), `@wvdse` 8	visibile solo al team di questo progetto

Che cosa significhi ciascun numero nel wiki e in questo plugin è spiegato nel riferimento tecnico.

Il livello public concede al gruppo @ALL il grado 2. DokuWiki legge lo stesso numero come diritto di modificare una pagina esistente. Su uno spazio dei nomi vuoto ciò è irrilevante; su uno spazio dei nomi con pagine wiki apre l'editor a tutti i visitatori.

I permessi si trovano in un blocco gestito del file conf/acl.auth.php, fra le righe # BEGIN wkdoadogit-managed e # END wkdoadogit-managed. Non modificate quel blocco a mano – impostate invece il livello del mount.

Lo spazio dei nomi del mount

Dopo la registrazione il repository compare nell'elenco dei mount con il proprio spazio dei nomi:

code:dokuwiki-plugins:wkdoadogit

La colonna Regole indica se i permessi scritti corrispondono al livello (written), mancano (NOT written) o divergono. Con il livello public nascono quattro righe in conf/acl.auth.php:

# 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

Lo spazio dei nomi del mount è virtuale. Porta permessi ma non pagine, e il mount non ne crea alcuna. Se aprite /doku.php?id=code:dokuwiki-plugins:wkdoadogit vedrete una pagina vuota. Non è un guasto – il repository lo mostra la sezione successiva.

La pagina con il browser del repository

Un repository viene disegnato dove un autore colloca la marcatura. Essa funziona solo su una pagina interna al progetto DWDO, perché il browser cerca la connessione attraverso il progetto di quella pagina.

Aprite nell'editor la pagina repos del vostro progetto: /doku.php?id=it:projects:dwplugins:repos&do=edit.
Inserite la marcatura {{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit}}.
Salvate la pagina.

Ora compaiono l'intestazione con il nome del repository, il contrassegno del livello e il nome del ramo, insieme all'albero della cartella radice.

La forma della marcatura è {{wk:adogit>connessione:progetto:repository[:ramo[:percorso]]}}:

Campo	Significato	Se lo omettete
`connessione`	la chiave della connessione (`wvds`), non il suo numero	è obbligatorio
`progetto`	il nome del progetto in Azure DevOps	è obbligatorio
`repository`	il nome del repository	è obbligatorio
`ramo`	ramo, tag o commit	vale il ramo predefinito del repository
`percorso`	la cartella da cui parte l'albero	vale la radice del repository

Per collocare il browser in una regione laterale della shell, aggiungete region=toc: {{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit region=toc}}.

Le schede Branches e Tags nell'intestazione sono visibili ma inattive. Il ramo mostrato si sceglie nella marcatura, non nell'interfaccia.

La marcatura già pronta la offre anche l'elenco dei mount: nel menu di riga del mount scegliete Mostra questo repository in una pagina wiki. Lì si trovano entrambe le marcature con i valori già inseriti.

Apertura di una cartella e di un file

Una cartella nell'albero si apre selezionandola. Il contenuto si carica solo all'apertura e in quel momento il permesso viene verificato di nuovo, perciò l'albero non proviene mai dalla cache condivisa delle pagine.

La cartella si può anche stabilire in anticipo, con il quinto campo della marcatura:

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

Un file si apre selezionandolo. Compare il cassetto di wksourceview e il file viene disegnato con l'evidenziazione della sintassi. Senza quel plugin non c'è il cassetto; l'albero rimane.

Chi ha il permesso di scrittura trova inoltre un pulsante accanto a ogni file e, nell'intestazione, il pulsante Nuovo ramo/tag. La procedura è descritta in modificare un file ed eseguire il commit dal wiki.

Sopra l'albero si trova il pannello richiudibile Come ottenere questo repository, con l'indirizzo per clone, il download ZIP e il collegamento ai token personali. Compare solo per il livello 2 o superiore; vedi clonare un repository.

Incorporamento del codice sorgente

Questa sezione è facoltativa. Un singolo file si può disegnare anche direttamente sulla pagina, senza browser:

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

La differenza fra le due marcature, le opzioni di resa e i limiti sono descritti in mostrare codice sorgente su una pagina wiki.

Risultato atteso

La pagina it:projects:dwplugins:repos mostra l'intestazione del repository wkdoadogit con il contrassegno del livello e il nome del ramo.
Le cartelle si aprono e i file compaiono nel cassetto del codice sorgente.
Un lettore senza permesso di lettura su code:dokuwiki-plugins:wkdoadogit non vede sulla stessa pagina né l'albero né il nome del repository, ma soltanto una scheda di stato.
In conf/acl.auth.php, dentro il blocco gestito, si trovano quattro righe di questo mount.

Quando il token personale non serve

Il token personale è un token per i client git, non per il wiki. Dentro il wiki non serve mai.

Atto	Token personale	Che cosa vale invece
consultare l'albero	no	permesso di lettura (livello 1 o superiore) sullo spazio dei nomi del mount
aprire un file e incorporare con `{{source>ado:…}}`	no	lo stesso permesso di lettura
modificare ed eseguire il commit dal wiki	no	permesso di scrittura (livello 8) sullo spazio dei nomi del mount
download dell'archivio ZIP	no	livello 2 o superiore
`git clone` o `git pull` fuori dal wiki	sì	livello 2 o superiore e un token valido
`git push` fuori dal wiki	sì	livello 4 o superiore e un token valido

Su Azure DevOps si autentica in ogni caso l'account di servizio. Il token personale dice soltanto chi nel wiki sta chiedendo.

Se qualcosa non funziona

Che cosa vedete	Causa più probabile
«Questo repository non è collegato a questo wiki.»	la marcatura indica una chiave di connessione errata, un nome di progetto o di repository errato — oppure il mount non è registrato
«Non avete il permesso di lettura su questo repository.»	il mount esiste, ma il livello non vi comprende
«Il servizio sorgente ADO non è disponibile.»	la connessione, l'elenco dei server ammessi, il segreto o l'estensione `curl` mancante
«Non è stato possibile caricare il repository.»	non è stato possibile analizzare la marcatura oppure il ramo indicato non esiste
la pagina mostra il testo della marcatura in chiaro	la pagina si trova fuori dalla radice dei progetti oppure il plugin non è attivo

La diagnostica completa con le procedure è nella Diagnostica.

Passi successivi

Come mostrare codice sorgente su una pagina wiki – mostrare codice sorgente su una pagina wiki
Come modificare un file ed eseguire il commit dal wiki – modificare un file ed eseguire il commit dal wiki
Come clonare un repository montato – clone, pull e push e il token personale
Concetti – livello di visibilità, permessi e limiti