woodpecker-authoring-pipelines git:20261017.f0972a6A

Immutable. This exact content never changes and is served at /api/v1/blob/28067c85e0b4cf1a.

---
name: woodpecker-authoring-pipelines
description: Use when writing or editing `.woodpecker.yml` or `.woodpecker/*.yaml`, porting a GitHub Actions or other CI config to Woodpecker, checking whether a Woodpecker config is valid, or when a Woodpecker step behaves differently than it does locally (shell syntax, file permissions, a service on localhost).
---

# Authoring Woodpecker pipelines

## Validate before pushing

```bash
woodpecker-cli lint .woodpecker.yml    # a file, or a .woodpecker/ directory
```

Exit 0 prints `Config is valid`. Errors print one line each and exit 1. It needs no server and no login, so it works on any machine with the CLI. A warning like "consider adding a `when` block with an `event` filter" is advice, not an error: without one, a step runs on every event.

`woodpecker-cli exec` runs a pipeline locally in Docker. It is documented upstream but untested here, so treat the first run as an experiment.

## Where "works locally, fails in CI" comes from

These are Woodpecker runtime facts, seen in real pipelines. Details in [references/runtime-facts.md](references/runtime-facts.md).

- Step `commands` run under `sh` (dash on Debian images), not bash. Bashisms such as `[[ ]]` and `source` fail.
- The clone is owned by root and steps run as root. Tests that check file permissions or refuse to run as root behave differently.
- Services are reached by their service name (`postgres:5432`), not `localhost`.
- A step with `failure: ignore` can fail while the pipeline shows green.

## Conventions

Trigger rules, base images and file layout are choices each repo makes. Read the repo's own CLAUDE.md and copy a sibling repo's pipeline before inventing structure.