The Complete Production SOP: How to Deploy and Run Woodpecker CI Community Container-Native Pipelines in Autonomous AI Agents
Step-by-step SOP to install and run Woodpecker CI Community Container-Native Pipelines in Codex, Claude Code, and Cursor. Verified prompts, YAML syntax, and fixes.
Technical Overview & Architectural Context
Autonomous coding agents often stumble when generating CI/CD pipelines for self-hosted container-native platforms like Woodpecker CI. Because Woodpecker diverged from Drone CI, LLMs regularly hallucinate outdated v0.8 Drone syntax, confuse Drone's proprietary extensions with Woodpecker's v2/v3 step syntax, or introduce malformed service-networking topologies. Unconstrained agents also misconfigure Docker socket bindings (`/var/run/docker.sock`) or inject plaintext credentials directly into pipeline manifests instead of leveraging native Woodpecker secret encryption. The `woodpecker-ci-community-engine` skill introduces strict deterministic SOP boundaries for Claude Code, Codex, Cursor, and Windsurf. By enforcing a declarative schema for `.woodpecker.yaml`, formalizing server-to-agent communication via `WOODPECKER_RPC_SECRET`, and defining container service dependencies (e.g., PostgreSQL, Redis), this skill prevents agents from breaking build queues and ensures production-ready container isolation across AMD64 and ARM64 runner fleets.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules.
Agent runtimes such as Claude Code and Cursor scan defined directories (`~/.agents/skills` or `.agents/skills` in the project root) for declarative operational profiles. Mounting `woodpecker-ci-community-engine` informs the LLM of accurate YAML schemas, triggers, and container networking boundaries, superseding ungrounded training priors.
mkdir -p ~/.agents/skills/woodpecker-ci-community-engine && curl -fsSL https://askills.dev/api/skills/woodpecker-ci-community-engine/raw -o ~/.agents/skills/woodpecker-ci-community-engine/SKILL.md---
name: "woodpecker-ci-community-engine"
description: "Run a lightweight, open-source community fork of Drone CI on your own servers."
metadata:
author: "Woodpecker CI"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "deploy woodpecker ci"
- "write .woodpecker.yaml"
- "woodpecker ci docker agent"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Place the SKILL.md at the repository root in `.cursor/skills/` or `.agents/skills/` to enable hot-reloading across collaborative developer environments without modifying global system prompts.
Ensure `fs_write` is scoped strictly to `workspace` so agents cannot overwrite global docker daemon configurations or host system secrets outside the project.
Environment Secrets & Dependency Validation
Inject required environment variables safely without leaking secrets into conversation history.
Woodpecker CI requires secure shared secrets for agent-to-server RPC communication and VCS OAuth credentials. Ensure these values reside in ignored local environment files or encrypted repository secrets rather than raw LLM system prompts or version control.
openssl rand -hex 32 | tr -d '\n' > .woodpecker_secret && echo "WOODPECKER_RPC_SECRET=$(cat .woodpecker_secret)" >> .env.ci && echo ".woodpecker_secret" >> .gitignore && echo ".env.ci" >> .gitignore#!/usr/bin/env bash
set -euo pipefail
RPC_SECRET=$(openssl rand -hex 32)
cat <<EOF > .env.woodpecker
WOODPECKER_RPC_SECRET=${RPC_SECRET}
WOODPECKER_HOST=https://ci.example.com
WOODPECKER_GITEA=true
WOODPECKER_GITEA_URL=https://git.example.com
WOODPECKER_GITEA_CLIENT_ID=your-client-id
WOODPECKER_GITEA_CLIENT_SECRET=your-client-secret
EOF
chmod 600 .env.woodpeckerNever let agents print the content of `.env.woodpecker` or `.woodpecker_secret` in conversational output; enforce secret suppression rules in agent instructions.
Ensure `.env.woodpecker` is explicitly added to `.gitignore`. If an agent stages environment configuration containing RPC tokens, it exposes full control of the pipeline runner.
Intent Matching & Trigger Invocation
Verify deterministic activation using tested natural language prompts.
Instruct the runtime using precise trigger phrases registered in the frontmatter metadata. When triggering pipeline generation or server compose definitions, reference container images explicitly to avoid obsolete Drone-style plugin declarations.
woodpecker-cli lint .woodpecker.yaml || docker run --rm -v $(pwd):/repo -w /repo woodpeckerci/woodpecker-cli:latest lint .woodpecker.yamlwhen:
- event: [push, pull_request]
branch: ${CI_REPO_DEFAULT_BRANCH}
services:
database:
image: postgres:16-alpine
environment:
POSTGRES_USER: test_user
POSTGRES_PASSWORD: test_password
POSTGRES_DB: test_db
ports:
- 5432
steps:
test:
image: node:20-alpine
commands:
- corepack enable
- pnpm install --frozen-lockfile
- pnpm test:integrationUse `when` blocks at the top level or per step rather than deprecated Drone `when:` syntax keys to minimize schema re-evaluations and token usage.
Do not configure `privileged: true` on steps unless building container images with Kaniko or DinD, as this introduces severe agent host vulnerabilities.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks before accepting agent deliverables.
Verify the syntax of generated `.woodpecker.yaml` and `docker-compose.yml` manifests against official schema validators. Enforce a clean exit code before finalizing the workspace changes.
docker run --rm -v "$(pwd):/work" -w /work woodpeckerci/woodpecker-cli:latest lint .woodpecker.yaml && docker compose -f docker-compose.woodpecker.yml config -q#!/usr/bin/env bash
set -euo pipefail
echo "Checking Woodpecker CI pipeline definition..."
if ! command -v woodpecker-cli &> /dev/null; then
docker run --rm -v "$(pwd):/work" -w /work woodpeckerci/woodpecker-cli:latest lint .woodpecker.yaml
else
woodpecker-cli lint .woodpecker.yaml
fi
echo "Pipeline syntax is valid."Inspect `git diff .woodpecker.yaml` to confirm that the agent did not replace modern matrix or service syntax with deprecated single-container workflows.
Running `woodpecker-cli lint` without local Docker mounting will fail if local cli binaries are missing; always provide the containerized fallback command.
Real-World Scenario: Deploying Full-Stack Node.js Test Pipeline with Postgres Service Container
“write .woodpecker.yaml for our Node.js and TypeScript project. Include a Postgres 16 service container, cache pnpm node_modules, run migrations, and execute tests on push to main.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent reverted to legacy Drone 0.8 syntax (using deprecated `pipeline:` root key instead of `steps:`) or indented the `when` condition improperly.
sed -i 's/^pipeline:/steps:/g' .woodpecker.yaml && woodpecker-cli lint .woodpecker.yamlRoot Cause: Service container networking in Woodpecker isolates services by their service name within the internal bridge network; the step attempted to connect to `localhost:5432` instead of `database:5432`.
Ensure application tests use `DATABASE_URL=postgres://test_user:test_password@database:5432/test_db` instead of `localhost` inside `.woodpecker.yaml` step environment blocks.Frequently Asked Questions (Woodpecker CI Community Container-Native Pipelines SOP)
Q:Can I use Woodpecker CI Community Container-Native Pipelines across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres strictly to universal SKILL.md specifications. Simply place the file inside `.agents/skills/woodpecker-ci-community-engine/SKILL.md` at your repository root to enable uniform execution across Codex, Claude Code, Cursor, and Windsurf.
Q:How does Woodpecker CI Community Container-Native Pipelines prevent context window overflow during long agent sessions?
By isolating the SOP into succinct declarative rules with strict trigger phrases, the runtime only injects necessary YAML schemas and CLI validation gates into context when triggered, avoiding token-heavy schema dumps in every prompt iteration.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It restricts agent file actions exclusively to the workspace directory (`fs_write: workspace`) and enforces unprivileged container steps without exposing the raw host Docker socket.
Ready to equip your autonomous agent with Woodpecker CI Community Container-Native Pipelines?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.