diff --git a/.woodpecker.yml b/.woodpecker.yml
index 53493c4..2433db0 100644
--- a/.woodpecker.yml
+++ b/.woodpecker.yml
@@ -1,7 +1,14 @@
+# Woodpecker CI - All 21 services + migrate run in parallel via matrix
+# Woodpecker executes each matrix entry as a separate pipeline concurrently
+
 when:
   branch: [main, high-performance]
   event: push
 
+# Limit concurrent pipelines to avoid overwhelming resources
+concurrency:
+  limit: 4
+
 matrix:
   SERVICE:
     - gateway
@@ -50,6 +57,7 @@ steps:
       cache: false
 
 ---
+# Separate pipeline for database migrations (runs independently)
 when:
   branch: [main, high-performance]
   event: push