Migrate To Plugin Suites
Available from divekit v2.45.0; earlier releases use the flat plugin model documented in the command pages.
Who Needs This
Origins that were set up before plugin suites list their plugins by a flat name
such as pmd or jacoco-pit, without a suite in front of it. Those origins
have to be converted once. An origin created with a current Divekit is already
on the new model and needs nothing.
Running the command tells you which case you are in:
divekit plugin migrate
If the origin is already converted, the command says so and stops. Otherwise it prints the full plan.
Migrate each origin separately, and use -d <distribution> when a distribution
carries its own plugin state.
Read The Plan First
divekit plugin migrate on its own is a dry run. It changes nothing and prints
the plan as a diff: which plugin becomes which suite plugin, which
configuration files move where, which files are removed.
The mapping for the plugins Divekit ships is:
| Before | After |
|---|---|
pmd | maven/pmd |
surefire | maven/surefire |
jacoco-pit | maven/jacoco-pit |
Read the plan before applying it. It is the only place where you see the whole change at once.
Apply
divekit plugin migrate --apply
Before the first write, everything the migration would overwrite is copied to
.divekit/backup/plugin-migrate-<timestamp>/, next to a backup.json listing
what was replaced and what was newly created. The apply then performs the plan
it printed.
Two things move without you having to touch them:
- Plugin configuration written by
divekit plugin configure, including the legacytest-command.jsonof JaCoCo/PIT, moves to the new per-plugin paths under.divekit/plugins/<suite>/<plugin>/. Materialized feedback assets move with it. - Manual report overrides are rewritten to the new plugin names. An override that still named a flat plugin would stop matching once results arrive under a suite path, so this happens together with the layout change rather than being left to you.
The old per-plugin CI files under .gitlab/ci/divekit/plugins/ are removed
rather than moved. Plugin jobs are now composed into the evaluation pipeline
itself, so the trigger jobs that included those files disappear in the same
step and nothing would read them again.
Plugins That Need Attention
A plugin the mapping does not cover cannot be placed automatically: a flat name
carries no suite, so putting it under maven would be a guess. The migration
lists such plugins as needing manual attention and leaves them out of the new
state. Their old entries stay readable in the backup.
Re-attach such a plugin as an external plugin of a suite once its repository has been ported to the current plugin contract. Until then it does not run.
Roll Back
divekit plugin migrate --rollback
This restores the most recent migration backup: files that were replaced come back, files the migration created are removed.
Plugin state is the last thing an apply writes, after the files, the overrides, and the recomposed pipeline. A run that is interrupted in between therefore leaves an origin that still counts as unmigrated, and the same migration can simply be run again. When a run fails, its message names the rollback command for what it had already changed.
After The Migration
The migration deliberately leaves the locked versions and image digests empty, so resolve them explicitly:
divekit plugin update
This locks the suite’s plugin versions and image digests, which is what makes the pipeline reproducible. For repositories that already exist, push the change out afterwards:
divekit patch ci -d ST2M4