Consistent and reliable plugin settings parsing

[Taywee]

Plugin settings have some unpredictable behavior. Given this settings block:

settings:
  alpha: beta
  gamma: [delta]
  epsilon: [zeta, eta, 'arg with , comma']
  theta:
    iota: kappa
    lambda: [mu, nu]
    xi:
      omicron: pi
      rho: sigma
  tau-upsilon: phi
  chi_psi: omega
  boolean-true: true
  boolean-false: true
  number: 1337
  literals:
    boolean-true: true
    boolean-false: true
    number: 1337

I get these environment variables:

"PLUGIN_ALPHA": "beta"
"PLUGIN_THETA": "{\"iota\":\"kappa\",\"lambda\":[\"mu\",\"nu\"],\"xi\":{\"omicron\":\"pi\",\"rho\":\"sigma\"}}"
"PLUGIN_LITERALS": "{\"boolean-false\":true,\"boolean-true\":true,\"number\":1337}"
"PLUGIN_GAMMA": "delta"
"PLUGIN_NUMBER": "1337"
"PLUGIN_BOOLEAN_FALSE": "true"
"PLUGIN_EPSILON": "zeta,eta,arg with , comma"
"PLUGIN_CHI_PSI": "omega"
"PLUGIN_BOOLEAN_TRUE": "true"
"PLUGIN_TAU_UPSILON": "phi"

It looks like strings, booleans, and numbers turn into strings, arrays turn into comma-separated strings, and maps turn into json-encoded objects. null causes an error and refuses to run the pipeline entirely.

This is useful for very simple cases, and when you know exactly what the incoming structure is, but it doesn't let you discern top-level booleans from strings, or array arguments with embedded commas vs separate array elements. If you want case-sensitivity or to distinguish between hyphens or underscores, you're out of luck. Additionally, if you want to allow a setting to be a string, array, or object, it makes it extra fiddly to reliably parse it, compared to just having everything json-encoded.

It would be cool to have another variable, named something like WOODPECKER_PLUGIN_SETTINGS that just contains the entire settings block encoded to a json object. Leave the existing ones for backward compatibility with existing plugins (and for easier use from shell script entrypoints), and let the plugin author decide what level of convenience and control they want.

[6543]

all exept base types are converted into json ... this is a feature, so you can have advanced config structures interpreted by the plugin ...

e.g. see buildx plugin and the logins

[Taywee]

Yes, except:

• array values with commas in the strings are ambiguous. Notice my epsilon: [zeta, eta, 'arg with , comma'] became "PLUGIN_EPSILON": "zeta,eta,arg with , comma". It's actually not clear that the comma is part of one of the values.
• If I want a setting to have the option to be set as a string or a map, then I can't be sure right off the bat whether I should parse it as json or not. Also, value: '"test"' would successfully parse as json and lose the quotation marks, even if they were supposed to be part of the value.

That said, I see the value in not having all the settings as JSON, because otherwise all shell scripts would need to integrate a json tool like jq. I think the above behavior is a good default to cover for the simple cases; I just would appreciate an escape hatch to get the unmodified settings in their original structure.

[6543]

null causes an error and refuses to run the pipeline entirely.

this I would say is an error ... I would expect an empty env var ... e.g. PLUGIN_NULL=''

[Taywee]

For top-level settings, yes, a blank value makes sense, but even:

settings:
  alpha:
    beta: gamma
    delta: null

Causes it to fail, even though that should be rolled into the JSON value as a json false. Also, the UI gives no indication of error. The webhook gives an error response and the UI doesn't report any failure.

[6543]

WOODPECKER_PLUGIN_SETTINGS

like that idea ...

[6543]

-> enhancement request/proposal