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 | - | Skip verification of TLS certificate | | | SOCKS_PROXY | none | SOCKS5 proxy to use for connections | | | SOCKS_PROXY_OFF | none | Do not use SOCKS5 proxy |

Creating plugin

package main

import (
	"context"

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

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",
			Sources:     cli.EnvVars("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: &Settings{},
	}

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

	p.Run()
}

Documentation

Index

• Constants
• func Flags() []cli.Flag
• func HTTPClientFromContext(c *cli.Command) *http.Client
• func SetupConsoleLogger(c *cli.Command) error
• type Author
• type Commit
• type ExecuteFunc
• type Forge
• type Metadata
  • func MetadataFromContext(c *cli.Command) 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

Constants

const (
	ForgeTypeGitea     = "gitea"
	ForgeTypeForgejo   = "forgejo"
	ForgeTypeGitHub    = "github"
	ForgeTypeGitLab    = "gitlab"
	ForgeTypeBitbucket = "bitbucket"
)

const (
	EventTypePush        = "push"
	EventTypePullRequest = "pull_request"
	EventTypeTag         = "tag"
	EventTypeDeployment  = "deployment"
	EventTypeCron        = "cron"
	EventTypeManual      = "manual"
)

Functions

func Flags

func Flags() []cli.Flag

Flags has the cli.Flags for the Woodpecker plugin.

func HTTPClientFromContext

func HTTPClientFromContext(c *cli.Command) *http.Client

func SetupConsoleLogger

func SetupConsoleLogger(c *cli.Command) 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 Forge

type Forge struct {
	Type string `json:"type,omitempty"`
	URL  string `json:"url,omitempty"`

	// Deprecated: Please use URL instead.
	Link string `json:"link,omitempty"`
}

Forge defines metadata for integration with a forge.

type Metadata

type Metadata struct {
	Repository     Repository `json:"repo,omitempty"`
	Pipeline       Pipeline   `json:"curr,omitempty"`
	Commit         Commit     `json:"commit,omitempty"`
	PreviousCommit Commit     `json:"previous_commit,omitempty"`
	Step           Step       `json:"step,omitempty"`
	System         System     `json:"sys,omitempty"`
	Forge          Forge      `json:"forge,omitempty"`

	// Deprecated: Please use Commit instead.
	Curr Commit

	// Deprecated: Please use PreviousCommit instead.
	Prev Commit `json:"prev,omitempty"`
}

Metadata defines runtime metadata.

func MetadataFromContext

func MetadataFromContext(c *cli.Command) 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
	// Context the plugin will use while executing.
	Context context.Context
}

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"`
	URL          string    `json:"url,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"`
	ChangedFiles []string  `json:"files,omitempty"`

	// Deprecated: Please use URL instead.
	Link string `json:"link,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 {
	RemoteID      string `json:"remote_id,omitempty"`
	Name          string `json:"name,omitempty"`
	Owner         string `json:"owner,omitempty"`
	Link          string `json:"link,omitempty"`
	URL           string `json:"url,omitempty"`
	CloneURL      string `json:"clone_url,omitempty"`
	Private       bool   `json:"private,omitempty"`
	DefaultBranch string `json:"default_branch,omitempty"`

	// Deprecated: Please use DefaultBranch instead.
	Branch string
}

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"`
	Platform string `json:"arch,omitempty"`
	Version  string `json:"version,omitempty"`
	URL      string `json:"url,omitempty"`

	// Deprecated: Please use URL instead.
	Link string `json:"link,omitempty"`
}

System defines runtime metadata for a ci/cd system.