Document how to create an own plugin

[6543]

• mention how settings are de-serialized
• mention build-in-env-vars
• mention best practics
• mention multiarch build, as official immages try to always have linux/amd64 & linux/arm64 images, and so other plugins should try to do so to

[6543]

tldr of how to do plugin is: all settings (arguments) are environment variables start with prefix PLUGIN_ most plugins use the build-in-env-vars for default values ... and as plugin you define the container entrypoint

simplest example I know of: https://github.com/vividboarder/drone-webdav

[smainz]

As I need to write some plugins, I am going to put together a small template bash plugin. What I plan is:

• Provide an example Dockerfile (alpine based)
• Provide a simple script plugin.sh which
  • reads settings
  • reads env vars
  • uses some built in env vars
  • doses some simple action
  • sets exit code
• Template for a Readme
• Build instructions / build script for the image
• CI config using woodpeckerci/plugin-docker-buildx to build the images
• Readme on how to use it

I could need some help:

1. Input on the structure / content of the Readme template. ATM I am going to structure it like this: https://github.com/smainz/woodpecker-git-setup/blob/main/Readme.md
2. Should the plugin prefer DRONE* or CI* env vars?
3. What are the 'best practices' mentioned above
4. What more would you like to see?

Question 2. somehow requires some vision on where Woodpecker will go and if we strive to be compatible with drone for the forseable future on the plugin level.

[anbraten]

1. Input on the structure / content of the Readme template. ATM I am going to structure it like this: https://github.com/smainz/woodpecker-git-setup/blob/main/Readme.md

That structure is nice. To be able to list projects in the official Woodpecker plugins list its in addition quite / even more important to provide a docs.md file.

Example docker-buildx:

• https://woodpecker-ci.org/plugins/Docker%20Buildx
• https://codeberg.org/woodpecker-plugins/plugin-docker-buildx/src/branch/main/docs.md

2. Should the plugin prefer DRONE* or CI* env vars?

If the plugin is mainly for Woopecker it should go with CI_ variables as they are more feature-rich. They are not as vendor specific as well.

3. What are the 'best practices' mentioned above

I guess that's a list that can be extended from time to time we experience any pitfalls. Currently I can think of things like supporting both CI_ and DRONE_ in case you want to use the plugin with DRONE_ as well. We could for example also provide a https://github.com/drone-plugins/drone-plugin-lib version for Woodpecker and link it here.

4. What more would you like to see?

It would be nice to suggest users to add the plugin to our index so the whole community can benefit from them.

[6543]

settings explained:

settings:
  some-bool: false   # will be PLUGIN_SOME_BOOL="false"
  some_String: hello # will be PLUGIN_SOME_STRING="hello"
  anInt: 3           # will be PLUGIN_ANINT="3"
  nonBasicType:      # will be json in PLUGIN_NONBASICTYPE="{"abc": "2", "list": [ "2", "3" ]}" 
    abc: 2
    list:
      - 2
      - 3

[lafriks]

Should probably mention: https://codeberg.org/woodpecker-plugins/go-plugin