plugin

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 30, 2026 License: Apache-2.0 Imports: 13 Imported by: 5

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
Optional: HTTP proxy support

HTTP proxy support is opt-in and must be explicitly enabled by the plugin author via EnableHTTPProxy: true in plugin.Options. When enabled, the following settings become available:

Settings Name Environment variable Default Description
http_proxy HTTP_PROXY none HTTP proxy URL for outgoing connections
https_proxy HTTPS_PROXY none HTTPS proxy URL for outgoing connections
no_proxy NO_PROXY none Comma-separated list of hosts to exclude from proxying

The settings are resolved in the following order of precedence:

  1. Plugin settings — PLUGIN_HTTP_PROXY, PLUGIN_HTTPS_PROXY, PLUGIN_NO_PROXY
  2. Lowercase env vars — http_proxy, https_proxy, no_proxy
  3. Uppercase env vars — HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Example Woodpecker CI pipeline configuration:

steps:
  - name: my-plugin
    image: my-plugin:latest
    settings:
      http_proxy: http://proxy.example.com:3128
      https_proxy: http://proxy.example.com:3128
      no_proxy: "localhost,internal.example.com"

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,
		EnableHTTPProxy: true, // opt-in to HTTP proxy support
	})

	p.Run()
}

Documentation

Index

Constants

View Source 
const (
	ForgeTypeGitea     = "gitea"
	ForgeTypeForgejo   = "forgejo"
	ForgeTypeGitHub    = "github"
	ForgeTypeGitLab    = "gitlab"
	ForgeTypeBitbucket = "bitbucket"
)
View Source 
const (
	EventTypePush        = "push"
	EventTypePullRequest = "pull_request"
	EventTypeTag         = "tag"
	EventTypeDeployment  = "deployment"
	EventTypeCron        = "cron"
	EventTypeManual      = "manual"
)

Variables

This section is empty.

Functions

func Flags 

func Flags() []cli.Flag

Flags has the cli.Flags for the Woodpecker plugin.

func HTTPClientFromContext 

func HTTPClientFromContext(c *cli.Command, httpProxyEnabled bool) *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 added in v0.3.0 

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
	// EnableHTTPProxy allows plugins to opt-in to HTTP/HTTPS proxy support.
	// When true, PLUGIN_HTTP_PROXY, PLUGIN_HTTPS_PROXY and PLUGIN_NO_PROXY
	// are accepted as settings and applied to the HTTP client.
	EnableHTTPProxy bool
}

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 {
	App *cli.Command

	// 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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.