Diagrams in GitLab CI/CD

TL;DR

1. Check every merge request

Add the component to .gitlab-ci.yml:

1include:2  - component: gitlab.com/plotwork/plotwork-component/plotwork@0.1.03    inputs:4      paths: 'README.md docs/**/*.md'5
6plotwork-diagrams:7  rules:8    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

The job is named by the input job-name, plotwork-diagrams by default, so a job of that name in your own file adds rules, tags, or needs to it. Without rules, the job runs in every pipeline.

A stale picture fails the job, and the log names the file and the line of the fence:

stale: docs/architecture.md needs sync  line 3: This diagram has no picture under it.

To fix it, run npx -y @buun_group/plotwork@0.3.0 sync on the same files and commit the Markdown and the SVGs it writes.

2. Fail a merge 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 add the component a second time in drift mode:

1include:2  - component: gitlab.com/plotwork/plotwork-component/plotwork@0.1.03    inputs:4      job-name: diagrams-drift5      mode: drift6
7diagrams-drift:8  rules:9    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

The job writes .plotwork/junit.xml and hands it to GitLab as a test report, so each generated diagram is a test in the merge request, failed when it drifted. The log names each change, such as Added 1 node (logs).

On a large project, check only the sources whose files changed on the branch:

1include:2  - component: gitlab.com/plotwork/plotwork-component/plotwork@0.1.03    inputs:4      job-name: diagrams-drift5      mode: drift6      since: origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME7
8diagrams-drift:9  variables:10    GIT_DEPTH: 0

3. Write the diagrams again

1include:2  - component: gitlab.com/plotwork/plotwork-component/plotwork@0.1.03    inputs:4      job-name: diagrams-generate5      mode: generate6
7diagrams-generate:8  rules:9    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

The job makes every diagram again in its workspace and keeps .plotwork/plotwork.patch in its artifacts for a week. Download it, run git apply plotwork.patch, and commit. The component holds no token and pushes nothing; a later job of your own can commit the patch with a project access token.

4. Send drift runs to the dashboard

An organisation on a plan with the drift dashboard can see every project's drift in one place. Make an organisation API key in the portal, add it to the project (or the group) as the CI/CD variable PLOTWORK_API_KEY, masked and protected, and set report-drift:

1include:2  - component: gitlab.com/plotwork/plotwork-component/plotwork@0.1.03    inputs:4      job-name: diagrams-drift5      mode: drift6      report-drift: true

A refusal, such as a plan with no dashboard, is a line in the log and fails nothing. A protected variable reaches only protected branches and tags, so a merge request pipeline from another branch sends nothing unless the variable is unprotected.

The dashboard names a repository as group/project. A project in a subgroup, such as acme/platform/web, is not sent yet, and the log says so.

With no key

A trusted publisher lets the job report with no key in the project. An owner or admin adds the project under Keys and CI, CI/CD, Add GitLab, then the include sets keyless:

1include:2  - component: gitlab.com/plotwork/plotwork-component/plotwork@0.1.03    inputs:4      job-name: diagrams-drift5      mode: drift6      report-drift: true7      keyless: true

The job asks GitLab for an ID token with api-url as its audience, swaps it at the API for a token that lives 15 minutes, and sends the run with it. The ID token is taken out of the job's environment before the command line runs, and neither token is printed. A PLOTWORK_API_KEY that is set still wins. A refused swap is a line in the log and fails nothing.

5. Inputs

The job keeps .plotwork/ as artifacts, on failure too: junit.xml (drift), report.json (drift with report-drift), and plotwork.patch (generate).

6. Versions and runners

Pin the component to a release, such as @0.1.0, and move the pin in a change you review. Each release of the component pins a stable release of the command line in cli-version, so a new release of either never changes your pictures by itself. To try a newer command line before the component moves, set cli-version, run sync with that release on your machine, and commit the pictures in the same change.

The job needs a runner that runs a container image (the Docker or Kubernetes executor) and can reach the npm registry. For a runner with no access to the registry, point npm at your own mirror with the CI/CD variable NPM_CONFIG_REGISTRY, and set image to an image of your registry.

See also