Azure DevOps needs separate documentation

[gpaulissen]

Hi,

When I wondered how to increase the pom version in an automated way on Azure DevOps I stumbled on this plugin.
It is a very nice and elegant solution.
But it took me much too much time to get it working.
I hope you can add this documentation to the documentation web site.

These are my observations:

1. I use DevOps Artifacts and its recommendations for repositories and distributionManagement
2. I use the Azure DevOps pipeline task Maven Authenticate to create a settings.xml with the server id's recommended in the previous step.
3. The default HTTPS connection for this plugin does not work: I get git-receive-pack not permitted on the repository when the plugin tries to change the repo.
4. Hence the plugin needs SSH and it needs a different name than {project.distributionManagement.repository.id} because you run into troubles when your project inherits a parent POM with the repo being equal to the plugin server id: it will download the Artifact parent POM first and then Maven thinks that the server is using HTTPS. There is no problem when there is no POM inheritance.
5. So I add a suffix (-ssh) to the plugin serverId: ${project.distributionManagement.repository.id}${multi-module-maven-release-plugin.suffix}.
6. I use a global settings file ssh-settings.xml (saved as an Azure DevOps secure file) with those servers defined again with username and password (strangely enough).
7. I use the Azure DevOps Install SSH Key task to set up SSH.
8. I have created the SSH keys with ssh-keygen: ssh-keygen -t rsa -m PEM since Azure only supports an older private key format, i.e. RSA not OPENSSH.
9. I have uploaded the private key id_rsa.
10. I have created a SSH variables group with some variables (known host entry, passphrase, public key).

Only then I get what I need.

Relevant sections in the POM:

      <plugin>
        <groupId>com.github.danielflower.mavenplugins</groupId>
        <artifactId>multi-module-maven-release-plugin</artifactId>
        <configuration>
          <!-- Here we need the same repository id as in distributionManagement but with a suffix to distinguish it from the HTTPS id. -->
          <!-- Now we need to use SSH (if property scm.git.ssh is true), not HTTPS. -->
          <!-- See also azure-pipelines.yml. -->
          <serverId>${project.distributionManagement.repository.id}${multi-module-maven-release-plugin.suffix}</serverId>
          <NoChangesAction>ReleaseNone</NoChangesAction>
        </configuration>
      </plugin>

I have attached the ssh-settings.xml and the Azure DevOps pipelines YAML
azure.zip