woodpecker/docs/docs/30-administration/11-forges/100-addon.md

Addon forges

If the forge you're using does not comply with Woodpecker's requirements or your setup is too specific to be added to Woodpecker's core, you can write your own forge using an addon forge.

:::warning Addon forges are still experimental. Their implementation can change and break at any time. :::

:::danger You need to trust the author of the addon forge you use. It can access authentication codes and other possibly sensitive information. :::

Usage

To use an addon forge, download the correct addon version. Then, you can add the following to your configuration:

WOODPECKER_ADDON_FORGE=/path/to/your/addon/forge/file

In case you run Woodpecker as container, you probably want to mount the addon binary to /opt/addons/.

Bug reports

If you experience bugs, please check which component has the issue. If it's the addon, do not raise an issue in the main repository, but rather use the separate addon repositories. To check which component is responsible for the bug, look at the logs. Logs from addons are marked with a special field addon containing their addon file name.

List of addon forges

If you wrote or found an addon forge, please add it here so others can find it!

Be the first one to add your addon forge!

Creating addon forges

Addons use RPC to communicate to the server and are implemented using the go-plugin library.

Writing your code

This example will use the Go language.

Directly import Woodpecker's Go packages (go.woodpecker-ci.org/woodpecker/woodpecker/v2) and use the interfaces and types defined there.

In the main function, just call "go.woodpecker-ci.org/woodpecker/v2/server/forge/addon".Serve with a "go.woodpecker-ci.org/woodpecker/v2/server/forge".Forge as argument. This will take care of connecting the addon forge to the server.

Example structure

package main

import (
  "context"
  "net/http"

  "go.woodpecker-ci.org/woodpecker/v2/server/forge/addon"
  forgeTypes "go.woodpecker-ci.org/woodpecker/v2/server/forge/types"
  "go.woodpecker-ci.org/woodpecker/v2/server/model"
)

func main() {
  addon.Serve(config{})
}

type config struct {
}

// `config` must implement `"go.woodpecker-ci.org/woodpecker/v2/server/forge".Forge`. You must directly use Woodpecker's packages - see imports above.