mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-12-03 07:06:30 +00:00
93 lines
3.8 KiB
Markdown
93 lines
3.8 KiB
Markdown
|
# Creating addons
|
||
|
|
|
||
|
|
Addons are written in Go.
|
||
|
|
|
||
|
|
## Writing your code
|
||
|
|
|
||
|
|
An addon consists of two variables/functions in Go.
|
||
|
|
|
||
|
|
1. The `Type` variable. Specifies the type of the addon and must be directly accessed from `shared/addons/types/types.go`.
|
||
|
|
2. 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](#return-types).
|
||
|
|
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:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
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
|
||
|
|
|
||
|
|
```go
|
||
|
|
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.
|
||
|
|
```
|