diff --git a/CI-CD-Pipeline.md b/CI-CD-Pipeline.md
new file mode 100644
index 0000000..234f007
--- /dev/null
+++ b/CI-CD-Pipeline.md
@@ -0,0 +1,121 @@
+# CI/CD Pipeline
+
+The project uses Drone CI to build and publish images to the Gitea container registry.
+
+---
+
+## Main Pipeline Responsibilities
+
+The pipeline builds:
+
+```text
+romexis-payload
+romexis-firebird-payload
+romexis-base-jre:11-amd64
+romexis-base-jre:11-arm64
+romexis-server:<version>-amd64
+romexis-server:<version>-arm64
+romexis-server:<version> multiarch manifest
+migration-service
+```
+
+---
+
+## Payload Build Logic
+
+The Windows payload build checks version definitions and copy-map changes.
+
+Desired behavior:
+
+| Change | Behavior |
+|---|---|
+| New version added | build only new version |
+| Existing URL changed | force rebuild affected version |
+| Copy map changed | rebuild all payload versions |
+| Extraction script changed | rebuild all payload versions |
+
+---
+
+## Firebird Payload Build
+
+The Firebird payload is built after the Windows Romexis payload step.
+
+It uses:
+
+```text
+romexis-firebird-payload/romexis-firebird-versions.env
+```
+
+The build pushes:
+
+```text
+romexis-firebird-payload:latest
+```
+
+The server image consumes the shared Firebird payload image.
+
+---
+
+## Server Build
+
+The server build pulls:
+
+```text
+ROMEXIS_PAYLOAD_IMAGE
+ROMEXIS_FIREBIRD_PAYLOAD_IMAGE
+ROMEXIS_BASE_IMAGE
+```
+
+Then builds the final runtime image for each architecture.
+
+---
+
+## Push vs Load
+
+In CI, use `--push` for buildx output when publishing images.
+
+This avoids unnecessary local image loading and can reduce worker time.
+
+---
+
+## Common CI Troubleshooting
+
+### Build is too fast after cache cleanup
+
+This may mean the pipeline skipped the build because the registry image already exists.
+
+Look for log lines like:
+
+```text
+already exists
+Skipping rebuild
+docker manifest inspect
+```
+
+Force rebuild by changing the pipeline condition or setting the force rebuild variable.
+
+### latest tag not found
+
+If the server Dockerfile references:
+
+```text
+romexis-firebird-payload:latest
+```
+
+then the Firebird payload pipeline must push `latest`.
+
+Build command should include:
+
+```bash
+-t "$FIREBIRD_PAYLOAD_IMAGE:latest"
+```
+
+### Payload missing from final image
+
+Check the final image:
+
+```bash
+docker run --rm --entrypoint find \
+  gitea.buchhorster.de/patrick/romexis-server:<tag> \
+  /opt -maxdepth 3 -type f
+```