Getting started

Nix development shell

If you use Nix, you can skip the install steps below. The repository contains a flake.nix that does it all for you:

nix develop

This opens a shell with Go, make, Node.js, pnpm, protoc and all development tools. The tools are built with the same Go version as Woodpecker. Only pre-commit is not included.

Install Go

Install Golang as described by this guide. You need at least the version that is set in the go.mod file.

info

An older Go version can still build Woodpecker, as it downloads the needed toolchain on its own. But tools that are installed with go install, like golangci-lint, are then built with the old version and refuse to work:

Error: can't load config: the Go language version (go1.26) used to build golangci-lint is lower than the targeted Go version (1.27.0)

In this case update Go and install the tools again.

Install make

GNU Make is a tool which controls the generation of executables and other non-source files of a program from the program's source files (https://www.gnu.org/software/make/).

Install make on:

• Ubuntu: apt install make - Docs
• Windows
• Mac OS: brew install make

Install development tools (optional)

The make targets use some tools to lint, format and generate code. You can install them with:

make install-tools

They are installed with go install, so make sure that the bin folder of your Go path (go env GOPATH) is part of your PATH.

If a tool is not installed, make lint, make format and make generate start it with go run instead. This works too, but is slower.

To generate the gRPC code, which is part of make generate, you also need protoc. It is not installed by make install-tools.

Install Node.js & pnpm

Install Node.js if you want to build Woodpecker's UI or documentation.

For dependency installation (node_modules) of UI and documentation of Woodpecker the package manager pnpm is used. This guide describes the installation of pnpm.

Install pre-commit (optional)

Woodpecker uses pre-commit to allow you to easily autofix your code. To apply it during local development, take a look at pre-commits documentation.

Create a .env file with your development configuration

Similar to the environment variables you can set for your production setup of Woodpecker, you can create a .env file in the root of the Woodpecker project and add any needed config to it.

A common config for debugging would look like this:

WOODPECKER_OPEN=true
WOODPECKER_ADMIN=your-username

WOODPECKER_HOST=http://localhost:8000

# github (sample for a forge config - see /docs/administration/forge/overview for other forges)
WOODPECKER_GITHUB=true
WOODPECKER_GITHUB_CLIENT=<redacted>
WOODPECKER_GITHUB_SECRET=<redacted>

# agent
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET=a-long-and-secure-password-used-for-the-local-development-system
WOODPECKER_MAX_WORKFLOWS=1

# enable if you want to develop the UI
# WOODPECKER_DEV_WWW_PROXY=http://localhost:8010

# if you want to test webhooks with an online forge like GitHub this address needs to be set and accessible from public server
WOODPECKER_EXPERT_WEBHOOK_HOST=http://your-address.com

# disable health-checks while debugging (normally not needed while developing)
WOODPECKER_HEALTHCHECK=false

# WOODPECKER_LOG_LEVEL=debug
# WOODPECKER_LOG_LEVEL=trace

Setup OAuth

Create an OAuth app for your forge as described in the forges documentation.

Developing with VS Code

You can use different methods for debugging the Woodpecker applications. One of the currently recommended ways to debug and test the Woodpecker application is using VS-Code or VS-Codium (Open-Source binaries of VS-Code) as most maintainers are using it and Woodpecker already includes the needed debug configurations for it.

To launch all needed services for local development, you can use "Woodpecker CI" debugging configuration that will launch UI, server and agent in debugging mode. Then open http://localhost:8000 to access it.

As a starting guide for programming Go with VS Code, you can use this video guide:

Debugging Woodpecker

The Woodpecker source code already includes launch configurations for the Woodpecker server and agent. To start debugging you can click on the debug icon in the navigation bar of VS-Code (ctrl-shift-d). On that page you will see the existing launch jobs at the top. Simply select the agent or server and click on the play button. You can set breakpoints in the source files to stop at specific points.

Testing & linting code

To test or lint parts of Woodpecker, you can run one of the following commands:

test server code

make test-server

test agent code

make test-agent

test cli code

make test-cli

test datastore/database related code like migrations of the server

make test-server-datastore

lint go code

make lint

lint UI code

make lint-ui

test UI code

make test-ui

If you want to test a specific Go file, you can also use:

go test -race -timeout 30s -tags test go.woodpecker-ci.org/woodpecker/v3/<path-to-the-package-or-file-to-test>

warning

Always pass -tags test. Many test files and test helpers, like the dummy backend, are only compiled with the test build tag. Without it go test skips these tests without any hint! Make targets do it for you.

Or you can open the test-file inside VS-Code and run or debug the test by clicking on the inline commands:

Run applications from terminal

If you want to run a Woodpecker applications from your terminal, you can use one of the following commands from the base of the Woodpecker project. They will execute Woodpecker in a similar way as described in debugging Woodpecker without the ability to really debug it in your editor.

start server

go run ./cmd/server

info

The server embeds the web UI from web/dist/ at compile time. If the UI is not built yet, compiling and running the server with go run will fail with:

web/web.go:26:12: pattern all:dist/*: no matching files found

Either build the UI once with make build-ui or create a placeholder with:

mkdir -p web/dist/ && echo "test" > web/dist/index.html

start agent

go run ./cmd/agent

execute cli command

go run ./cmd/cli [command]