plugin

README

Library for creating Woodpecker CI plugins

Provides basic structure and helpers to load Woodpecker CI environment variables while also supporting reading Drone CI environment variables where available.

Adds logging support based on zerolog library and allows configurable HTTP client library.

Builtin settings

Settings Name	Environment variable	Default	Description
log_level	-	info	Sets log level (panic, fatal, error, warn, info, debug, trace)
skip_verify	-	false	-
	SOCKS_PROXY	none	SOCKS5 proxy to use for connections
	SOCKS_PROXY_OFF	none	Do not use SOCKS5 proxy

Creating plugin

import (
    "context"

    "codeberg.org/woodpecker-plugins/go-plugin"
    "github.com/urfave/cli/v2"
    "github.com/rs/zerolog/log"
)

type Settings struct {
    // TODO: Plugin settings
    SampleFlag string
}

type Plugin struct {
    *plugin.Plugin
    Settings *Settings
}

func (p *Plugin) Flags() []cli.Flag {
    return []cli.Flag{
        // TODO: Add flags
        &cli.StringFlag{
            Name:    "sample.flag",
            Usage:   "sample flag",
            EnvVars: []string{"PLUGIN_SAMPLE_FLAG"},
            Destination: &p.Settings.SampleFlag,
        },
    }
}

func (p *Plugin) Execute(ctx context.Context) error {
    // TODO: Implement execution
    log.Debug().Msg("executed")
    return nil
}

func main() {
    p := &Plugin{
        &Settings{}
    }
    
    p.Plugin = plugin.New(Options{
        Name: "sample-plugin",
        Description: "Sample plugin",
        Flags: p.Flags(),
        Execute: p.Execute,
    })

    p.Run()
}

Documentation

Index

• func Flags() []cli.Flag
• func HTTPClientFromContext(ctx *cli.Context) *http.Client
• func SetupConsoleLogger(c *cli.Context) error
• type Author
• type Commit
• type ExecuteFunc
• type Metadata
  • func MetadataFromContext(ctx *cli.Context) Metadata
• type Options
• type Pipeline
• type Plugin
  • func New(opt Options) *Plugin
  • func (p *Plugin) HTTPClient() *http.Client
  • func (p *Plugin) Run()
• type Repository
• type Step
• type System

Functions

func Flags

func Flags() []cli.Flag

Flags has the cli.Flags for the Woodpecker plugin.

func HTTPClientFromContext

func HTTPClientFromContext(ctx *cli.Context) *http.Client

func SetupConsoleLogger

func SetupConsoleLogger(c *cli.Context) error

SetupConsoleLogger sets up the console logger.

Types

type Author

type Author struct {
	Name   string `json:"name,omitempty"`
	Email  string `json:"email,omitempty"`
	Avatar string `json:"avatar,omitempty"`
}

Author defines runtime metadata for a commit author.

type Commit

type Commit struct {
	Sha          string `json:"sha,omitempty"`
	Ref          string `json:"ref,omitempty"`
	Refspec      string `json:"refspec,omitempty"`
	PullRequest  string `json:"pull_request,omitempty"`
	SourceBranch string `json:"source_branch,omitempty"`
	TargetBranch string `json:"target_branch,omitempty"`
	Branch       string `json:"branch,omitempty"`
	Tag          string `json:"tag,omitempty"`
	Message      string `json:"message,omitempty"`
	Author       Author `json:"author,omitempty"`
}

Commit defines runtime metadata for a commit.

type ExecuteFunc

type ExecuteFunc func(ctx context.Context) error

ExecuteFunc defines the function that is executed by the plugin.

type Metadata

type Metadata struct {
	Repository Repository `json:"repo,omitempty"`
	Pipeline   Pipeline   `json:"curr,omitempty"`
	Curr       Commit     `json:"commit,omitempty"`
	Prev       Commit     `json:"prev,omitempty"`
	Step       Step       `json:"step,omitempty"`
	System     System     `json:"sys,omitempty"`
}

Metadata defines runtime metadata.

func MetadataFromContext

func MetadataFromContext(ctx *cli.Context) Metadata

MetadataFromContext creates a Metadata from the cli.Context.

type Options

type Options struct {
	// Name of the plugin.
	Name string
	// Description of the plugin.
	Description string
	// Version of the plugin.
	Version string
	// Flags of the plugin.
	Flags []cli.Flag
	// Execute function of the plugin.
	Execute ExecuteFunc
}

Options defines the options for the plugin.

type Pipeline

type Pipeline struct {
	Number       int64     `json:"number,omitempty"`
	Status       string    `json:"status,omitempty"`
	Event        string    `json:"event,omitempty"`
	Link         string    `json:"link,omitempty"`
	DeployTarget string    `json:"target,omitempty"`
	Created      time.Time `json:"created,omitempty"`
	Started      time.Time `json:"started,omitempty"`
	Finished     time.Time `json:"finished,omitempty"`
	Parent       int64     `json:"parent,omitempty"`
}

Pipeline defines runtime metadata for a pipeline.

type Plugin

type Plugin struct {

	// Metadata of the current pipeline.
	Metadata Metadata
	// contains filtered or unexported fields
}

Plugin defines the plugin instance.

func New

func New(opt Options) *Plugin

New plugin instance.

func (*Plugin) HTTPClient

func (p *Plugin) HTTPClient() *http.Client

HTTPClient returns the http.Client instance.

func (*Plugin) Run

func (p *Plugin) Run()

Run the plugin.

type Repository

type Repository struct {
	Name     string `json:"name,omitempty"`
	Owner    string `json:"owner,omitempty"`
	Link     string `json:"link,omitempty"`
	CloneURL string `json:"clone_url,omitempty"`
	Private  bool   `json:"private,omitempty"`
	Branch   string `json:"default_branch,omitempty"`
}

Repository defines runtime metadata for a repository.

type Step

type Step struct {
	Number   int       `json:"number,omitempty"`
	Started  time.Time `json:"started,omitempty"`
	Finished time.Time `json:"finished,omitempty"`
}

Step defines runtime metadata for a step.

type System

type System struct {
	Name     string `json:"name,omitempty"`
	Host     string `json:"host,omitempty"`
	Link     string `json:"link,omitempty"`
	Platform string `json:"arch,omitempty"`
	Version  string `json:"version,omitempty"`
}

System defines runtime metadata for a ci/cd system.