Diagrams in Azure Pipelines

TL;DR

1. Install the extension

The extension is shared privately with each Azure DevOps organisation that asks for it until its public listing in the Visual Studio Marketplace opens. To get it now, ask us for access (opens in a new tab) with the name of your Azure DevOps organisation, or run the command line in a script step as CI usage shows.

Once the extension is shared with your organisation or listed, an organisation administrator installs it (Organization settings, Extensions, Shared or Browse marketplace, Plotwork diagrams, Install). Every project of the organisation can then use the task and the Plotwork service connection type.

2. Check every pull request

1trigger: none2pr:3  branches:4    include: [main]5
6pool:7  vmImage: ubuntu-latest8
9steps:10  - task: UseNode@111    inputs:12      version: 22.x13  - task: PlotworkDiagrams@114    inputs:15      mode: check16      paths: |17        README.md18        docs/**/*.md19      diagrams: |20        diagrams/**/*.diagram

For a repository in Azure Repos, a pr trigger in the file does nothing: add the pipeline as a build validation policy of the branch (Project settings, Repositories, Policies, Branch policies) instead.

check runs plotwork sync --check on the Markdown and plotwork validate on each .diagram file. Each stale picture and each mistake is an issue on its line, which the run's summary and the pull request show, and the Plotwork tab of the run lists every file with how to fix it. To fix a stale picture, run npx -y @buun_group/plotwork@0.3.0 sync on the same files and commit the Markdown and the SVGs it writes.

A rules section in the settings is checked too, with plotwork check.

3. Validate, redraw, and render

4. Fail a pull request on drift

When diagrams are made from Terraform, OpenAPI, Compose and other files, name them in sources of plotwork.config.json, as Diagrams as code describes. Then run the task in drift mode:

1steps:2  - task: UseNode@13    inputs:4      version: 22.x5  - task: PlotworkDiagrams@16    inputs:7      mode: drift

Each drifted diagram is an issue on its file, and the task publishes a test run in which each generated diagram is a test, failed when it drifted. On a pull request build in Azure Repos it writes one comment with the change table, the owners, and how to fix it, and edits that comment on later runs, to say so when everything is in step again (comment: auto, or always, or never). The comment needs Contribute to pull requests for the build service.

On a large repository, check only the sources whose files changed on the branch. The check needs the history up to the ref:

1steps:2  - checkout: self3    fetchDepth: 04  - task: UseNode@15    inputs:6      version: 22.x7  - task: PlotworkDiagrams@18    inputs:9      mode: drift10      since: origin/main

5. Write the diagrams again in a pull request

This pipeline runs every night on main, makes every diagram again from its files, and opens or updates one pull request with the ones that drifted:

1trigger: none2pr: none3
4schedules:5  - cron: '0 2 * * *'6    displayName: Regenerate diagrams7    branches:8      include: [main]9
10pool:11  vmImage: ubuntu-latest12
13steps:14  - checkout: self15    fetchDepth: 016  - task: UseNode@117    inputs:18      version: 22.x19  - task: PlotworkDiagrams@120    name: plotwork21    inputs:22      mode: generate23      onDrift: pr

Azure Pipelines skips a scheduled run when the branch has no new commit since the last successful scheduled run. Add always: true under the schedule to run every night anyway, for example so the drift dashboard always shows a recent run.

The task makes every diagram again in the workspace and uploads plotwork.patch as the pipeline artifact plotwork. Then onDrift says what to do with the drifted diagrams:

pr and commit push with the job's own access token, and only in Azure Repos. The task reads the token itself, so no env: mapping is needed. A pull request build runs on a merge commit, so pr and commit run on a push, a schedule, or a manual run. In a GitHub or Bitbucket repository the task cannot push: it says why, and the files and the patch stay for a later step of yours.

Build service permissions

Open Project settings, Repositories, the repository, Security, and choose the user <project> Build Service (<organisation>). Set these to Allow:

A branch policy on prBranch refuses the push too, so leave that branch free of policies. A pipeline whose job authorization scope is the whole collection runs as Project Collection Build Service (<organisation>) instead, so grant that user.

With publish: true, each source of the settings that has a publish section is published to Plotwork after the files are written, as Diagrams as code describes.

6. Connect to your organisation

check, validate, sync, render, and drift without reporting need no Plotwork account. Reporting drift, publishing, and an organisation's style rules (rulesOrg) do. The task takes the first credential it finds, in this order:

With a service connection and an organisation key

1. In the Plotwork portal, open the organisation, choose Keys & CI, and make a key that can do diagrams ("Diagrams" or "Diagrams and the audit log"). A key made "Audit log only" cannot report or publish, and a personal key is refused.
2. In Azure DevOps, open Project settings, Service connections, New service connection, and choose Plotwork.
3. Leave the API address as it is, paste the key into Organisation API key, name the connection (such as plotwork), and save. Grant it to the pipelines that use it, or approve it on the first run.
4. Set plotworkConnection to the connection's name:

1  - task: PlotworkDiagrams@12    inputs:3      mode: drift4      reportDrift: true5      plotworkConnection: plotwork6      organization: acme

To keep the key in a secret variable instead, map it into the step, because Azure Pipelines never puts a secret in the environment by itself:

1  - task: PlotworkDiagrams@12    inputs:3      mode: drift4      reportDrift: true5    env:6      PLOTWORK_API_KEY: $(PLOTWORK_API_KEY)

With no key, as a trusted publisher

1. In Azure DevOps, open Pipelines and choose the pipeline. Its address ends in ?definitionId=42: that number is the pipeline id. Renaming the pipeline keeps it.
2. In the Plotwork portal, open the organisation, choose Keys & CI, then CI/CD. Under Trusted publishers, choose Add trusted publisher, then Azure Pipelines.
3. Fill in the Azure DevOps organisation (acme in https://dev.azure.com/acme), the project, and the pipeline id. With the Azure DevOps connector connected, choose each from a list instead, and Branch suggests the pipeline's default branch.
4. Optionally name a branch (main, or a ref pattern such as refs/heads/release/*). Leave it blank for any branch. A pull request build's ref is refs/pull/<n>/merge, so an entry limited to main refuses pull request runs.
5. Choose what its runs can do: Publish diagrams to the library, Report drift to the Drift tab, or both. Give it a name you will recognise in the usage and the audit log, and save.
6. Run the pipeline with no service connection and no PLOTWORK_API_KEY. Choose Workflow beside the entry to copy a pipeline made for it.

The task asks Azure Pipelines for the job's OpenID Connect token with the job's own access token, which needs no service connection, and exchanges it for a Plotwork token that lasts 15 minutes. The first run that passes every other check pins the ids of the Azure DevOps organisation and project, and the entry shows a pin until then. The output signedInAs names the organisation and the trusted publisher. Trusted publishers says what is checked.

When more than one Plotwork organisation trusts the pipeline, set organization to the slug of the one to sign in to.

7. Report drift to the dashboard

An organisation on a plan with the drift dashboard sees every repository's drift in one place. This pipeline checks every pull request and every push to main, and sends each run to the dashboard:

1trigger:2  branches:3    include: [main]4pr:5  branches:6    include: [main]7
8pool:9  vmImage: ubuntu-latest10
11steps:12  - checkout: self13  - task: UseNode@114    inputs:15      version: 22.x16  - task: PlotworkDiagrams@117    inputs:18      mode: drift19      reportDrift: true

It signs in as a trusted publisher; add plotworkConnection to use a key instead. To report from the nightly pipeline of section 5, add reportDrift: true, and publish: true to publish too, to its generate step.

A refusal, such as a plan with no dashboard, is a note and fails nothing. The dashboard names a repository as owner/name: a GitHub repository as it is, and an Azure Repos repository as project/repository. A project whose name has a space is not sent yet, and the note says so.

8. Inputs

Give the task a name, such as plotwork, and a later step reads an output as $(plotwork.errors).

9. Versions and agents

The task is PlotworkDiagrams@1; its major version moves only with a change that breaks a pipeline. Each release of the extension pins a stable release of the command line in cliVersion, so an update of the extension never changes your pictures by itself. To try a newer command line first, set cliVersion, run sync with that release on your machine, and commit the pictures in the same change.

A self-hosted agent needs Node 22 or later with npx on its path, git, and the npm registry or a mirror of it (set NPM_CONFIG_REGISTRY on the agent). Signing in as a trusted publisher needs Azure DevOps Services; Azure DevOps Server sets no System.OidcRequestUri.

10. Troubleshooting

See also