refactor: upstream sync strategy with dynamic GENERAL.txt

.woodpecker/ipq60xx.yml

@@ -4,7 +4,10 @@ when:
 
 variables:
   WRT_REPO: "https://github.com/VIKINGYFY/immortalwrt.git"
-  WRT_BRANCH: "main"   # IPQ60XX 用 main
+  WRT_BRANCH: "main"
+  # Optional: Pin GENERAL.txt to a specific commit for reproducible builds
+  # Leave empty or set to 'main' to always use latest
+  # UPSTREAM_GENERAL_REF: ""
 
 steps:
   - name: init-env
@@ -16,6 +19,12 @@ steps:
       - apt-get install -y --no-install-recommends ca-certificates curl git rsync dos2unix jq
       - bash -c 'bash <(curl -fsSL https://build-scripts.immortalwrt.org/init_build_environment.sh)'
 
+  - name: sync-configs
+    image: ubuntu:24.04
+    commands:
+      - chmod +x ${CI_WORKSPACE}/Scripts/sync_upstream_config.sh
+      - ${CI_WORKSPACE}/Scripts/sync_upstream_config.sh
+
   - name: build-ipq60xx-wifi-yes
     image: ubuntu:24.04
     commands:
@@ -23,16 +32,21 @@ steps:
       - cd wrt-yes
       - ./scripts/feeds update -a
       - ./scripts/feeds install -a
+
       - cd package
       - dos2unix ${CI_WORKSPACE}/Scripts/*.sh || true
       - chmod +x ${CI_WORKSPACE}/Scripts/*.sh
       - ${CI_WORKSPACE}/Scripts/Packages.sh ${CI_WORKSPACE}/Scripts/Handles.sh
+
       - cd ..
-      - cat ${CI_WORKSPACE}/Config/IPQ60XX-WIFI-YES.txt ${CI_WORKSPACE}/Config/GENERAL.txt > .config
+      - cat ${CI_WORKSPACE}/Config/IPQ60XX-WIFI-YES.txt \
+            ${CI_WORKSPACE}/Config/GENERAL.upstream.txt \
+            ${CI_WORKSPACE}/Config/GENERAL.local.txt > .config
       - ${CI_WORKSPACE}/Scripts/Settings.sh
       - make defconfig -j"$(nproc)"
       - make download -j"$(nproc)"
       - make -j"$(nproc)" || make -j1 V=s
+
       - mkdir -p ${CI_WORKSPACE}/artifacts/ipq60xx-wifi-yes
       - cp -rf bin/targets ${CI_WORKSPACE}/artifacts/ipq60xx-wifi-yes/
 
@@ -43,15 +57,20 @@ steps:
       - cd wrt-wifi
       - ./scripts/feeds update -a
       - ./scripts/feeds install -a
+
       - cd package
       - dos2unix ${CI_WORKSPACE}/Scripts/*.sh || true
       - chmod +x ${CI_WORKSPACE}/Scripts/*.sh
       - ${CI_WORKSPACE}/Scripts/Packages.sh ${CI_WORKSPACE}/Scripts/Handles.sh
+
       - cd ..
-      - cat ${CI_WORKSPACE}/Config/IPQ60XX-WIFI.txt ${CI_WORKSPACE}/Config/GENERAL.txt > .config
+      - cat ${CI_WORKSPACE}/Config/IPQ60XX-WIFI.txt \
+            ${CI_WORKSPACE}/Config/GENERAL.upstream.txt \
+            ${CI_WORKSPACE}/Config/GENERAL.local.txt > .config
       - ${CI_WORKSPACE}/Scripts/Settings.sh
       - make defconfig -j"$(nproc)"
       - make download -j"$(nproc)"
       - make -j"$(nproc)" || make -j1 V=s
+
       - mkdir -p ${CI_WORKSPACE}/artifacts/ipq60xx-wifi
       - cp -rf bin/targets ${CI_WORKSPACE}/artifacts/ipq60xx-wifi/

Config/GENERAL.local.txt

@@ -0,0 +1,6 @@
+# Your overrides/additions here
+# This file is merged with GENERAL.upstream.txt during build
+
+# Example packages to add:
+# CONFIG_PACKAGE_luci-app-xxx=y
+# CONFIG_PACKAGE_luci-app-yyy=y

Config/GENERAL.txt

@@ -1,18 +0,0 @@
-# ===== Common / minimal baseline =====
-# 说明：这里只放"你想始终启用的包/功能"
-# 后续你要加 luci-app、内核模块等，就在这里追加 CONFIG_PACKAGE_xxx=y
-
-# LuCI (可按需开关)
-CONFIG_PACKAGE_luci=y
-CONFIG_PACKAGE_luci-ssl=y
-CONFIG_PACKAGE_uhttpd=y
-CONFIG_PACKAGE_uhttpd-mod-ubus=y
-
-# SSH
-CONFIG_PACKAGE_openssh-sftp-server=y
-
-# 常用工具
-CONFIG_PACKAGE_curl=y
-CONFIG_PACKAGE_wget=y
-CONFIG_PACKAGE_htop=y
-CONFIG_PACKAGE_tcpdump=y

README.md

@@ -1,18 +1,57 @@
 # OpenWrt/ImmortalWrt IPQ60XX Build (Woodpecker)
 
-This repo is a build-orchestration repo:
+This repo is a build-orchestration repo that compiles IPQ60XX firmware using Woodpecker CI.
-- Config/: .config fragments (device sets + GENERAL)
-- Scripts/: package injection / tweaks
-- files/: OpenWrt overlay (copied into firmware rootfs)
-- .woodpecker/: CI pipelines
 
-Targets:
+## Quick Start
-- IPQ60XX-WIFI-YES (from VIKINGYFY/OpenWRT-CI)
-- IPQ60XX-WIFI (from davidtall/OpenWRT-CI)
 
-How to add packages:
+1. **Set up Woodpecker**: Enable this repository in Woodpecker UI
-1) If available in feeds: append `CONFIG_PACKAGE_xxx=y` to `Config/GENERAL.txt`
+2. **Optional config**: Edit `Config/GENERAL.local.txt` to add custom packages
-2) If not in feeds or need pinned repo: add clone/remove logic in `Scripts/Packages.sh`
+3. **Trigger build**: Push to `main` branch or click manual trigger
 
-Artifacts:
+## Architecture
-- Saved into `artifacts/` in pipeline workspace.
+
+### Three upstream layers
+
+| Layer | Purpose | Source |
+|-------|---------|--------|
+| SOURCE | Firmware source code | `VIKINGYFY/immortalwrt.git` (main branch) |
+| CI-TEMPLATE | Config templates | `davidtall/OpenWRT-CI` (GENERAL.txt dynamic) |
+| YOUR-DELTA | Your customizations | This repo (edit only here) |
+
+### Build targets
+
+- **IPQ60XX-WIFI-YES**: Based on VIKINGYFY/OpenWRT-CI
+- **IPQ60XX-WIFI**: Based on davidtall/OpenWRT-CI
+
+Both targets merge: Device Config + Upstream GENERAL + Your LOCAL overrides
+
+## How to add packages
+
+### Feeds packages
+Add to `Config/GENERAL.local.txt`:
+```
+CONFIG_PACKAGE_luci-app-xxx=y
+CONFIG_PACKAGE_openssh-sftp-server=y
+```
+
+### Custom packages
+Edit `Scripts/Packages.sh` to clone custom repos
+
+## Documentation
+
+Detailed guide: See [docs/SKILLS.md](docs/SKILLS.md)
+
+## Artifacts
+
+Build outputs are saved to `artifacts/` directory:
+- `artifacts/ipq60xx-wifi-yes/` - Firmware from WIFI-YES config
+- `artifacts/ipq60xx-wifi/` - Firmware from WIFI config
+
+## Dependencies
+
+This repository pulls configs from:
+- [VIKINGYFY/OpenWRT-CI](https://github.com/VIKINGYFY/OpenWRT-CI)
+- [davidtall/OpenWRT-CI](https://github.com/davidtall/OpenWRT-CI)
+
+Source firmware:
+- [VIKINGYFY/immortalwrt](https://github.com/VIKINGYFY/immortalwrt)

Scripts/Handles.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-# Placeholder for Scripts/Handles.sh
-# Please download manually from: https://raw.githubusercontent.com/VIKINGYFY/OpenWRT-CI/main/Scripts/Handles.sh
-# Or run: curl -fsSL https://raw.githubusercontent.com/VIKINGYFY/OpenWRT-CI/main/Scripts/Handles.sh -o Scripts/Handles.sh
-set -euo pipefail
-echo "Handles.sh placeholder - please download the actual script"

Scripts/Packages.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-# Placeholder for Scripts/Packages.sh
-# Please download manually from: https://raw.githubusercontent.com/VIKINGYFY/OpenWRT-CI/main/Scripts/Packages.sh
-# Or run: curl -fsSL https://raw.githubusercontent.com/VIKINGYFY/OpenWRT-CI/main/Scripts/Packages.sh -o Scripts/Packages.sh
-set -euo pipefail
-echo "Packages.sh placeholder - please download the actual script"

Scripts/Settings.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-# Placeholder for Scripts/Settings.sh
-# Please download manually from: https://raw.githubusercontent.com/VIKINGYFY/OpenWRT-CI/main/Scripts/Settings.sh
-# Or run: curl -fsSL https://raw.githubusercontent.com/VIKINGYFY/OpenWRT-CI/main/Scripts/Settings.sh -o Scripts/Settings.sh
-set -euo pipefail
-echo "Settings.sh placeholder - please下载 the actual script"

Scripts/sync_upstream_config.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Sync GENERAL.txt from upstream davidtall/OpenWRT-CI
+# This ensures we always get the latest upstream config
+
+mkdir -p Config
+
+# Optional: Pin to a specific commit for reproducible builds
+# Set UPSTREAM_GENERAL_REF to a commit hash or branch name
+# Default: 'main' (always latest)
+UPSTREAM_GENERAL_REF="${UPSTREAM_GENERAL_REF:-main}"
+
+curl -fsSL \
+  "https://raw.githubusercontent.com/davidtall/OpenWRT-CI/${UPSTREAM_GENERAL_REF}/Config/GENERAL.txt" \
+  -o "Config/GENERAL.upstream.txt"
+
+echo "Synced GENERAL.txt from davidtall/OpenWRT-CI (${UPSTREAM_GENERAL_REF})"

docs/SKILLS.md

@@ -0,0 +1,115 @@
+# OpenWrt/ImmortalWrt IPQ60XX — Woodpecker Build Skills
+
+## Repo role
+This repo is a build-orchestration repo (configs + scripts + woodpecker pipeline).
+Upstream source is cloned during CI.
+
+## Upstream config sync strategy
+
+### Three-layer upstream model
+
+1. **SOURCE 上游（固件源码）**
+   - `WRT_REPO = https://github.com/VIKINGYFY/immortalwrt.git`
+   - `WRT_BRANCH = main`
+
+2. **CI-TEMPLATE 上游（配置/脚本参考）**
+   - 设备集（固定）：
+     - VIKINGYFY/OpenWRT-CI: `Config/IPQ60XX-WIFI-YES.txt`
+     - davidtall/OpenWRT-CI: `Config/IPQ60XX-WIFI.txt`
+   - 通用包（动态拉取）：
+     - `Config/GENERAL.upstream.txt` 编译时从 davidtall/OpenWRT-CI 下载
+
+3. **YOUR-DELTA（你自己的增量，永远只改这里）**
+   - `Config/GENERAL.local.txt` - 你的包/功能增量
+   - `Scripts/Packages.sh` - 需要固定仓库版本的第三方包/去冲突
+   - `Scripts/Handles.sh` - 脚本辅助函数
+   - `Scripts/Settings.sh` - kconfig 设置调整
+   - `files/` - 固件内默认配置覆盖
+
+## How config merging works
+
+During build, `.config` is assembled from THREE files in this order:
+
+```
+cat Config/IPQ60XX-WIFI-*.txt \
+    Config/GENERAL.upstream.txt \
+    Config/GENERAL.local.txt > .config
+```
+
+Later entries override earlier ones, so:
+- Device set config < Upstream GENERAL
+- Upstream GENERAL < Your local overrides
+
+## Where to add your packages
+
+### 1) If package exists in feeds
+Simply append `CONFIG_PACKAGE_xxx=y` to `Config/GENERAL.local.txt`
+
+Example:
+```
+CONFIG_PACKAGE_luci-app-adguardhome=y
+CONFIG_PACKAGE_luci-app-wireguard=y
+```
+
+### 2) If package is not in feeds / you need pinned repo
+Add clone/remove conflict logic in `Scripts/Packages.sh`
+This runs after feeds, before defconfig.
+
+Example:
+```bash
+# Clone a custom package repo
+git clone --depth=1 https://github.com/user/package.git package/custom-package
+
+# Remove conflicting packages
+rm -rf package/conflicting-package
+```
+
+## Fixing build issues with upstream changes
+
+If upstream GENERAL.txt breaks your build:
+
+### Quick fix (pin to a known good commit)
+Set `UPSTREAM_GENERAL_REF` in Woodpecker variables to a specific commit hash:
+```
+UPSTREAM_GENERAL_REF=abc123def456
+```
+
+### Permanent fix
+Override the problematic config in `Config/GENERAL.local.txt`
+
+## Woodpecker cron builds
+
+Create a cron job in Woodpecker UI for this repo:
+1. Go to Repository Settings > Schedules
+2. Add new schedule (e.g., daily at 03:00)
+3. Pipeline runs automatically on `event: cron`
+
+## Debugging
+
+To test config merging locally:
+```bash
+./Scripts/sync_upstream_config.sh
+cat Config/IPQ60XX-WIFI-YES.txt Config/GENERAL.upstream.txt Config/GENERAL.local.txt > test.config
+```
+
+## File structure
+
+```
+.
+├── .woodpecker/
+│   └── ipq60xx.yml          # Woodpecker pipeline
+├── Config/
+│   ├── IPQ60XX-WIFI-YES.txt # Device set A (static)
+│   ├── IPQ60XX-WIFI.txt     # Device set B (static)
+│   ├── GENERAL.local.txt    # YOUR overrides (edit this!)
+│   └── GENERAL.upstream.txt # Fetched at build time (DO NOT EDIT)
+├── Scripts/
+│   ├── sync_upstream_config.sh  # Pull GENERAL.txt from upstream
+│   ├── Packages.sh              # Package injection (edit as needed)
+│   ├── Handles.sh               # Helper functions
+│   └── Settings.sh               # kconfig tweaks
+├── files/                     # Rootfs overlay (optional)
+├── artifacts/                  # Build outputs (gitignored)
+└── docs/
+    └── SKILLS.md               # This file
+```