mirror of
https://github.com/woodpecker-ci/woodpecker.git
synced 2024-12-17 14:06:29 +00:00
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
|
# Addon forges
|
||
|
|
|
||
|
|
If the forge you're using does not comply with [Woodpecker's requirements](../../92-development/02-core-ideas.md#forges) 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:
|
||
|
|
|
||
|
|
```ini
|
||
|
|
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](https://github.com/hashicorp/go-plugin).
|
||
|
|
|
||
|
|
### 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
|
||
|
|
|
||
|
|
```go
|
||
|
|
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.
|
||
|
|
```
|