Creating addons

Addons are written in Go.

Writing your code

An addon consists of two variables/functions in Go.

The Type variable. Specifies the type of the addon and must be directly accessed from shared/addons/types/types.go.
The Addon function which is the main point of your addon. This function takes two arguments:
1. The zerolog logger you should use to log errors, warnings etc.
2. A slice of strings with the environment variables used as configuration.
It returns two values:
1. The actual addon. For type reference see table below.
2. An error. If this error is not nil, Woodpecker exits.

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

Return types

Addon type	Return type
`Forge`	`"go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge".Forge`
`Backend`	`"go.woodpecker-ci.org/woodpecker/woodpecker/v2/pipeline/backend/types".Backend`
`ConfigService`	`"go.woodpecker-ci.org/woodpecker/v2/server/plugins/config".ConfigService`
`SecretService`	`"go.woodpecker-ci.org/woodpecker/v2/server/model".SecretService`
`EnvironmentService`	`"go.woodpecker-ci.org/woodpecker/v2/server/model".EnvironmentService`
`RegistryService`	`"go.woodpecker-ci.org/woodpecker/v2/server/model".RegistryService`

Compiling

After you write your addon code, compile your addon:

go build -buildmode plugin

The output file is your addon which is now ready to be used.

Restrictions

Addons must directly depend on Woodpecker's core (go.woodpecker-ci.org/woodpecker/woodpecker/v2). The addon must have been built with excatly the same code as the Woodpecker instance you'd like to use it on. This means: If you build your addon with a specific commit from Woodpecker next, you can likely only use it with the Woodpecker version compiled from this commit. Also, if you change something inside of Woodpecker without committing, it might fail because you need to recompile your addon with this code first.

In addition to this, addons are only supported on Linux, FreeBSD and macOS.

:::info It is recommended to at least support the latest released version of Woodpecker. :::

Compile for different versions

As long as there are no changes to Woodpecker's interfaces or they are backwards-compatible, you can easily compile the addon for multiple version by changing the version of go.woodpecker-ci.org/woodpecker/woodpecker/v2 using go get before compiling.

Logging

The entrypoint receives a zerolog.Logger as input. Do not use any other logging solution. This logger follows the configuration of the Woodpecker instance and adds a special field addon to the log entries which allows users to find out which component is writing the log messages.

Example structure

package main

import (
  "context"
  "net/http"

  "github.com/rs/zerolog"
  "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge"
  forge_types "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/forge/types"
  "go.woodpecker-ci.org/woodpecker/woodpecker/v2/server/model"
  addon_types "go.woodpecker-ci.org/woodpecker/woodpecker/v2/shared/addon/types"
)

var Type = addon_types.TypeForge

func Addon(logger zerolog.Logger, env []string) (forge.Forge, error) {
  logger.Info().Msg("hello world from addon")
  return &config{l: logger}, nil
}

type config struct {
  l zerolog.Logger
}

// ... in this case, `config` must implement `forge.Forge`. You must directly use Woodpecker's packages - see imports above.

3.8 KiB Raw Blame History