Quickstart: the first Azure DevOps connection

The shortest way from “the plugin is installed” to “a connection reports ok, and no token sits in the configuration”. Four steps, about fifteen minutes.

Prerequisites

wkdoado, wkdocore, wkdostorage and wkcore are installed and enabled.
The PHP extension curl is present. Without it the screen reports Connector inactive.
A DWDO project exists — see the wkdocore quickstart. Without a project record the connection cannot be saved.
You hold the Maintainer role in that project. A reader may see the list of connections but not create one.
A personal access token for the organisation, with as few scopes as possible.
Somewhere to keep that token: wkvault, or a directory outside the web root.

Step 1: allow the host — nothing works before this

Admin → Configuration, section wkdoado, setting ado_host_allow.

The list is empty by default, and empty denies everything. It is not a filter over an otherwise open client; it is the entire permission to make a request at all.

Enter the exact host name, one per line or comma-separated:

dev.azure.com

No wildcards, no patterns. The list names the places this wiki may talk to, and a pattern would be a promise about places nobody has enumerated.

If the host name resolves to a loopback or private address — the normal case for an on-premises installation — also set ado_allow_private = 1. On this installation ado_host_allow is devops.wvds.it and ado_allow_private is 1.

Step 2: put the token somewhere referenceable

Do not enter the token into this plugin's configuration. There is deliberately no field for it.

Either store it in the vault and reference it (vault:ado-pat-acme), or set ado_secret_root to a directory outside the web root and place the token there as a file. That setting is empty by default too, and therefore disables file references entirely — fail-closed, like the allowlist.

Step 3: create the connection

The connection belongs to exactly one DWDO project and is therefore not set up in administration but on a project page. Open a project page and append the action:

/doku.php?id=en:projects:acme:start&do=wkdoado

Fill in under Add connection:

Field	What goes in it
Key	The connection's identifier; `[A-Za-z0-9_-]`, at most 64 characters.
Title	The label in the list.
Deployment	`services` for the `dev.azure.com` service, `server` for an on-premises installation.
Base URL	The server's base address.
Organization (services) / Collection (server)	Depending on the deployment.
API version	Default `7.0`.

Choose Add, then set the reference from step 2 on the connection's row via Set secret.

With deployment server the collection is usually already part of the base URL. Filling in Collection (server) as well appends it a second time and every call ends in HTTP 404. Name the collection in one place only.

Step 4: test

Choose Test on the connection's row.

Check the result

The Health column reads ok. When the test fails it names the cause instead of passing a single verdict — and the causes really do call for different answers:

Health	Meaning
host blocked	Step 1 is missing, or the host name does not match exactly.
unreachable	DNS, routing, or a private address without `ado_allow_private`.
TLS error	Certificate verification failed. Verification is always on; for an on-premises CA there is `ado_ca_bundle`.
unauthorized	The token is wrong, expired or lacks the scope.

Counter-check: wkdoado's configuration contains no token — only a reference on the connection.

Next step

wkdoadogit — make a repository of that organisation visible in the wiki.
wkvault — create the vault entry the reference points at.
wkdoado (German) — the package page: the client, the guard and all eight settings, among them the ado_max_bytes ceiling that truncates a large result rather than streaming it.