From 08383b64bfdc88378fca5a3568c349c35f9d47a6 Mon Sep 17 00:00:00 2001
From: epistemophiliac <epistemophiliac@zohomail.net>
Date: Tue, 16 Jun 2026 18:12:39 -0400
Subject: [PATCH] Add Jenkins setup doc (multibranch discover branches fix)

---
 README.md       |  2 +-
 docs/JENKINS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/JENKINS.md

diff --git a/README.md b/README.md
index 88e2f9a..528cb76 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ Jenkins runs the same checks on every build via [`Jenkinsfile`](Jenkinsfile):
 - `scripts/ci/validate-docker-compose.sh` — Coolify compose rules + `docker compose config`
 - `docker compose config` + pull pinned `frappe/erpnext` image
 
-**Jenkins:** Multibranch Pipeline → `https://git.aexoradao.com/epistemophiliac/erpnext.git` → Script Path `Jenkinsfile`
+**Jenkins:** see [docs/JENKINS.md](docs/JENKINS.md) — Multibranch needs **Discover branches** behaviour, or use a simple **Pipeline** job on `main`.
 
 Run locally:
 
diff --git a/docs/JENKINS.md b/docs/JENKINS.md
new file mode 100644
index 0000000..c4dcbe6
--- /dev/null
+++ b/docs/JENKINS.md
@@ -0,0 +1,56 @@
+# Jenkins setup (Forgejo)
+
+Repo: `https://git.aexoradao.com/epistemophiliac/erpnext.git`  
+Branch: `main`  
+Pipeline file: `Jenkinsfile` (repo root)
+
+## Option A — Simple Pipeline (fastest)
+
+If Multibranch shows an empty folder, use this instead.
+
+1. **New Item** → **Pipeline** → name `erpnext`
+2. **Pipeline** → Definition: **Pipeline script from SCM**
+3. SCM: **Git**
+   - Repository URL: `https://git.aexoradao.com/epistemophiliac/erpnext.git`
+   - Credentials: Forgejo user + access token
+   - Branch: `*/main`
+4. Script Path: `Jenkinsfile`
+5. **Save** → **Build Now**
+
+## Option B — Multibranch Pipeline
+
+Indexing succeeds but the folder stays empty when **Discover branches** is missing.
+
+1. **New Item** → **Multibranch Pipeline** → name `erpnext`
+2. **Branch Sources** → **Git**
+   - URL + credentials (same as above)
+3. **Behaviours** → **Add** → **Discover branches**
+   - Strategy: **All branches** (or include `main` via wildcard filter)
+4. **Build Configuration**
+   - Mode: **by Jenkinsfile**
+   - Script Path: `Jenkinsfile`
+5. **Save** → **Scan Repository Now**
+
+You should see a `main` branch under the folder. Click it → **Build Now**.
+
+### Optional: Forgejo webhook
+
+Install the **Gitea** plugin in Jenkins, then use **Gitea** as the branch source (Forgejo-compatible) for automatic scans on push.
+
+## Credentials
+
+**Manage Jenkins → Credentials → Add**
+
+- Kind: Username with password
+- Username: `epistemophiliac`
+- Password: Forgejo personal access token (repo read scope)
+
+## What the pipeline does
+
+- `scripts/ci/ci-readiness.sh`
+- `scripts/ci/validate-docker-compose.sh`
+- `docker compose config` (Coolify-safe compose)
+- `docker pull frappe/erpnext:<version>`
+- Archives `dist/docker-compose.coolify.yml`
+
+This validates the repo; **Coolify deploy is separate**.