Show an ADO repository in the wiki for the first time

This walkthrough takes one repository from Azure DevOps from nothing to a visible file on a wiki page. Seven sections follow the order in which you work; the last one is optional.

The values in the examples come from this installation. Replace them with your own.

• For the connection you need the manage role in the DWDO project. A reader may see the list of connections but cannot create one.
• For the mount you need administrator rights, because a mount writes site-wide permissions.
• wkcore, wkdocore, wkdostorage, wkdoado and wkdoadogit must be installed and enabled. Without wksourceview files do not open in the drawer.
• The DWDO project must exist twice: as a namespace below the project root (here {lang}:projects:) and as a record in DWDO storage. Without the record the connection cannot be saved.
• In the settings of wkdoado the name of the ADO server must appear in ado_host_allow. An empty list refuses every call.
• The secret (PAT) must live outside the database, as a vault:, file:, env: or enc: reference.
• The PHP extension curl must be available on the server. Without it the browser does not load and the git proxy fails.

The connection describes the ADO server and belongs to exactly one DWDO project. It is not set up in the admin area but on a project page.

1. Open any page of the project and append the action do=wkdoado, for example /doku.php?id=en:projects:dwplugins:start&do=wkdoado. The command palette opens the same screen through the entry Manage ADO connections.
2. If the connection is already in the list, note its key and move on to the next section.
3. Fill in the form for a new connection: Key (wvds; permitted characters [A-Za-z0-9_-], at most 64), Title, Deployment (services for the dev.azure.com service or server for an installation of your own), Base URL, if needed Organization (services) and Collection (server), and API version (default 7.0).
4. Choose Add.
5. In the connection's row choose the secret mode (vault:, file:, env: or enc:), enter the value and save. In vault: mode the value is the id of an entry in wkvault, on this installation adogit-service-pat.
6. Choose Test and wait for the outcome. The test distinguishes four causes: a forbidden server, an unreachable target, a certificate failure and an authentication failure.

Continue only once the test succeeds.

The mount binds the repository to a wiki namespace and writes the permissions for it.

1. Open Admin > ADO-Git Repo Mounts, directly /doku.php?do=admin&page=wkdoadogit_mounts.
2. Expand Register a mount.
3. On the 1. Connection screen choose the connection. The list shows it as project / key, for example dwplugins / wvds. Choose Next.
4. On the 2. ADO project screen choose the project, for example DokuWiki-Plugins. The connection supplies the list; when the server does not answer, the screen says so and offers a free-text field.
5. On the 3. Repositories screen tick one or more repositories, for example wkdoadogit. Adjust the Namespace template field if needed, choose the visibility tier, then choose Preview.
6. Read the 4. Preview screen. It shows what the tier grants, which namespace will be created, and every permission line that will be written. It also warns when the namespace already holds wiki pages.
7. Choose Register.

The mount is written first, the permissions second. If writing the permissions fails, the screen tells you; there is no silent intermediate state.

The namespace template defaults to code:{project}:{repo}. The placeholders {project} and {repo} are replaced with the names from Azure DevOps; any {lang} stays put and expands per language only when the permissions are written.

The tier is the only place where visibility is governed. Permissions are read on every request, so a change takes effect immediately.

What each number means in the wiki and in this plugin is explained in the technical reference.

The permissions live in a managed block of conf/acl.auth.php, between the lines # BEGIN wkdoadogit-managed and # END wkdoadogit-managed. Do not edit that block by hand – set the tier of the mount instead.

After registration the repository appears in the mount list with its namespace:

code:dokuwiki-plugins:wkdoadogit

The Rules column says whether the written permissions match the tier (written), are missing (NOT written) or diverge. At tier public four lines appear 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

A repository is drawn where an author places the markup. It works only on a page inside the DWDO project, because the browser looks up the connection through that page's project.

1. Open the repos page of your project in the editor: /doku.php?id=en:projects:dwplugins:repos&do=edit.
2. Insert the markup {{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit}}.
3. Save the page.

The header with the repository name, the tier badge and the branch name now appears, along with the tree of the root folder.

The grammar of the markup is {{wk:adogit>connection:project:repo[:ref[:path]]}}:

To place the browser in a side region of the shell, append region=toc: {{wk:adogit>wvds:DokuWiki-Plugins:wkdoadogit region=toc}}.

The Branches and Tags tabs in the header are visible but inactive. You choose the branch on display in the markup, not in the interface.

Open a folder in the tree by selecting it. Its content loads only when opened, and the permission is checked again at that moment, so the tree never comes from the shared page cache.

You can also set the folder in advance, through the fifth field of the markup:

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

Open a file by selecting it. The drawer of wksourceview appears and the file is drawn with syntax highlighting. Without that plugin there is no drawer; the tree remains.

Users with write permission also find a button beside every file and, in the header, the button New branch/tag. The procedure is described in editing a file and committing from the wiki.

Above the tree sits the collapsible panel Get this repository, carrying the address for clone, the ZIP download and a link to the personal tokens. It appears only for level 2 or more; see cloning a repository.

This section is optional. You can also draw a single file directly on the page, without the browser:

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

The difference between the two markups, the display options and the limits are described in showing source code on a wiki page.

• The page en:projects:dwplugins:repos shows the header of the wkdoadogit repository with the tier badge and the branch name.
• Folders open, and files appear in the source drawer.
• A reader without read permission on code:dokuwiki-plugins:wkdoadogit sees neither the tree nor the repository name on that same page, only a state card.
• Four lines for this mount stand inside the managed block of conf/acl.auth.php.

The personal token is a token for git clients, not for the wiki. Inside the wiki it is never needed.

The service account signs in to Azure DevOps in every case. The personal token only says who in the wiki is asking.

The full diagnostics with procedures are in Diagnostics.

• Show source code on a wiki page – show source code on a wiki page
• Edit a file and commit from the wiki – edit a file and commit from the wiki
• Clone a mounted repository – clone, pull and push, and the personal token
• Concepts – visibility tier, permissions and limits