Migrating username & secret password to credentials plugin

[Réda Housni Alaoui]

Hi all,

https://github.com/jenkinsci/sonar-gerrit-plugin/blob/905786a87ab70b3af130ea718472f05511efd650/src/main/java/org/jenkinsci/plugins/sonargerrit/config/GerritAuthenticationConfig.java#L25 is currently storing some credentials in 2 fields:

- String username

- Secret password

I'd like to replace those 2 fields with a credentials id from credentials plugin.

Is there a best practice for this kind of data migration? What should I do with the old field data? Should I automatically create one credentials instance per legacy username & password in a new readResolve method?

[Daniel Beck]

> On 8. Jan 2022, at 13:59, 'Réda Housni Alaoui' via Jenkins Developers <jenkin...@googlegroups.com> wrote:
>
> Is there a best practice for this kind of data migration? What should I do with the old field data? Should I automatically create one credentials instance per legacy username & password in a new readResolve method?

Re-saving automatically isn't great (you may lose configuration data accidentally), and otherwise you may readResolve the same content a bunch of times if it happens in job configs (on every restart, reload, when users POST config.xml to the API). If you don't deduplicate, this can get messy quickly.

Subversion Plugin 2.0 did an migration (1.x had Secret or similar non-Credentials user/pwd storage), so maybe looking at that helps. Git Plugin went through a similar migration I think. There were a bunch of problems though at least in Subversion, and I ended up with duplicated credentials at the time and spent quite a bit of time cleaning those up. I expect this isn't very easy to implement, but haven't looked at it in several years.

Another (fairly user hostile) solution could be to remove inline Secret support and replace it with credentialsId configuration; anyone updating will need to reconfigure all locations with username/password to have a corresponding credential. This might be doable/defensible when it's only a single global configuration location; less so if it affects hundreds of jobs individually.

Another option could be to add support for Credentials as an alternative (planning to retire inline auth config longer term). I think Artifactory Plugin did that a while ago. When you do, it's useful to inform admins by having warnings about the deprecated config on the UI (both in the config and perhaps an admin monitor). I don't think that readResolve is a great location for triggering those though, as I don't think you can easily get the context (for example the job). In matrix-auth 3.0 I ended up using a combination of Node/Item/SaveableListeners, @Initializers, and overriding JobProperty#setOwner to identify obsolete configuration and track them over time. Then wait a bit (many months), then remove the old config, giving people time to migrate.

Make sure to set hpi.compatibleSinceVersion when you drop support for the old way to configure things so admins aren't caught by surprise.

[Basil Crow]

Email Extension did this recently in jenkinsci/email-ext-plugin#325
and the follow-up bug fix jenkinsci/email-ext-plugin#332.

[Réda Housni Alaoui]

Thank you all.

I think I am going to take the automatic migration road.