Woodpecker Extension

Requires minimum woodpecker version 3.14

Resources

• Woodpecker extension
• HttpSig

Usage

Workflows are deduplicated by Configuration.name (the [workflows.*] key), preferring the response over the request.

Configuration

Config is loaded from a TOML file. The path is set via the WOODPECKER_EXTENSION_CONFIG environment variable (default: /etc/woodpecker-extension/config.toml).

[conf] — top-level

Key	Type	Default	Description
log_level	string	"Info"	Log level. One of: Error, Warn, Info, Debug, Trace
lookup_strategy	string	"ForgejoApi"	Repository info resolution strategy. Only ForgejoApi supported.

[http] — HTTP server

Key	Type	Default	Description
listen_addr	string	"0.0.0.0"	Bind address
listen_port	integer	8050	Bind port
health	string	"/health"	Health check endpoint path
openapi_path	string	"/openapi.json"	OpenAPI spec endpoint path
docs_path	string	"/docs"	Swagger UI endpoint path

[woodpecker] — authentication

Key	Type	Default	Description
public_key	string	required	Ed25519 public key in PEM format for HTTP signature verification

[endpoints] — global endpoint settings

Key	Type	Default	Description
verify_http_signature	bool	true	Global toggle for HTTP signature verification. When false, per-endpoint verification is also disabled.

[[endpoints.routes]] — route definitions

Each entry in this array of tables defines a workflow endpoint. Endpoint paths must not conflict with the health, openapi_path, or docs_path routes.

Key	Type	Default	Description
name	string	required	Human-readable route identifier
kind	string	required	Endpoint type. Only "Config" is currently supported.
path	string	required	HTTP path the extension listens on (e.g. /workflow/global)
combine_mode	string	"Union"	Rule combination strategy. "Union" (all matching rules) or "First" (first match wins)
rules	array	[]	Ordered list of rule names to evaluate
include_incoming_workflows	bool	false	Forward the incoming pipeline's own workflows unchanged
workflows	array	[]	Workflow names (keys in [workflows.*]) always injected, regardless of rule matches
verify_http_signature	bool	true	Per-endpoint signature verification. Only effective when the global toggle is also true.

[workflows.<name>] — named workflow definitions

Named workflows map a logical name to a file path on disk. The name is used as Configuration.name in the extension response instead of the file path. All workflows referenced in [[endpoints.routes]] or [rules.<name>] must be defined here.

Key	Type	Default	Description
path	string	required	File path to the workflow YAML on disk

[rules.<name>] — matching rules

Named rules define glob-based patterns to match against files in the repository root. Multiple rules can share the same endpoint via the rules list.

Key	Type	Default	Description
description	string	null	Optional human-readable description
match_patterns	array	[]	Glob patterns — all must match at least one root-level file (AND logic)
match_not_patterns	array	[]	Glob patterns — none may match any root-level file (exclusion)
match_labels	array	[]	Repository labels — all must be present in woodpecker.toml
match_not_labels	array	[]	Repository labels — none may be present in woodpecker.toml
workflows	array	[]	Workflow names (keys in [workflows.*]) to inject when this rule matches

Matching logic:

• If match_patterns is empty, the match requires nothing (vacuously true).
• If match_not_patterns is empty, nothing is excluded.
• Patterns use standard Unix glob syntax via the globset crate (e.g. *.py, src/**/*.rs, Cargo.toml).

Repository labels

Repositories can add a root-level woodpecker.toml file to provide labels used by global rules:

labels = ["destination:cluster", "destination:nix"]

For example:

[rules.cluster-nix]
match_labels = ["destination:cluster", "destination:nix"]
match_not_labels = ["destination:disabled"]
match_patterns = ["flake.nix"]
workflows = ["cluster-nix"]

File matching keeps its existing semantics. Label conditions and file conditions are combined with AND. A missing woodpecker.toml is treated as an empty label list. The file is read at the pipeline revision, and malformed TOML causes the request to fail with a 502 Bad Gateway response because the invalid configuration is repository-controlled upstream data.

Enum reference

Enum	Variants
LogLevel	Error, Warn, Info (default), Debug, Trace
LookupStrategy	ForgejoApi (default, only supported)
EndpointKind	Config (only supported)
CombineMode	Union (default, all matching rules), First (first match only)

Validation

At startup the server validates:

• None of the [[endpoints.routes]] paths conflict with the health, openapi_path, or docs_path routes.
• All workflow names referenced in [[endpoints.routes]] and [rules.<name>] are defined in [workflows.*] sections. Any validation failure causes the server to panic on start.

Full example

See config.example.toml for a complete annotated configuration with multiple endpoints and rules.

Development

Prerequisites

• Cargo (latest stable)
• Openapi-generator-cli

Fetch all dependencies using Nix

nix develop