fix(docs): stop autoupdate PRs from rewriting source URLs every run

Makefile

@@ -47,6 +47,20 @@ else
   DOC_VERSION ?= next
 endif
 
+# SOURCE_REF: stable git ref written into the displayed `source:` URL of generated docs.
+# Decoupled from BRANCH (which fetches content) so that patch releases of the same
+# minor don't churn every file's source URL on every release.
+#   v0    → main         (legacy bucket; many 0.x tags share this dir)
+#   next  → main         (trunk tracks upstream main)
+#   vX.Y  → release-X.Y  (the upstream long-lived branch for that minor)
+ifeq ($(DOC_VERSION),v0)
+  SOURCE_REF ?= main
+else ifeq ($(DOC_VERSION),next)
+  SOURCE_REF ?= main
+else
+  SOURCE_REF ?= release-$(patsubst v%,%,$(DOC_VERSION))
+endif
+
 # App lists (override on the command line: `make update-apps APPS="tenant redis"`)
 APPS       ?= tenant clickhouse foundationdb harbor redis mongodb openbao rabbitmq postgres nats kafka mariadb qdrant
 K8S       ?= kubernetes
@@ -64,19 +78,19 @@ SERVICES_DEST_DIR   ?= content/en/docs/$(DOC_VERSION)/operations/services
         init-version init-next release-next download-openapi download-openapi-all serve show-target
 
 update-apps:
-	./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)"
+	./hack/update_apps.sh --apps "$(APPS)" --dest "$(APPS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
 
 update-vms:
-	./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(BRANCH)"
+	./hack/update_apps.sh --apps "$(VMS)" --dest "$(VMS_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
 
 update-networking:
-	./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)"
+	./hack/update_apps.sh --apps "$(NETWORKING)" --dest "$(NETWORKING_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
 
 update-k8s:
-	./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)"
+	./hack/update_apps.sh --index --apps "$(K8S)" --dest "$(K8S_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)"
 
 update-services:
-	./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --pkgdir extra
+	./hack/update_apps.sh --apps "$(SERVICES)" --dest "$(SERVICES_DEST_DIR)" --branch "$(BRANCH)" --source-ref "$(SOURCE_REF)" --pkgdir extra
 
 update-oss-health:
 	./hack/update_oss_health.py

content/en/docs/v1.0/applications/clickhouse.md

@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/clickhouse.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/clickhouse/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/clickhouse/README.md
 -->
 
 

content/en/docs/v1.0/applications/foundationdb.md

@@ -6,7 +6,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/foundationdb.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/foundationdb/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/foundationdb/README.md
 -->
 
 

content/en/docs/v1.0/applications/harbor.md

@@ -7,7 +7,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/harbor.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/harbor/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/harbor/README.md
 -->
 
 

content/en/docs/v1.0/applications/kafka.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/kafka.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/kafka/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/kafka/README.md
 -->
 
 

content/en/docs/v1.0/applications/mariadb.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/mariadb.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/mariadb/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/mariadb/README.md
 -->
 
 

content/en/docs/v1.0/applications/mongodb.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/mongodb.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/mongodb/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/mongodb/README.md
 -->
 
 

content/en/docs/v1.0/applications/nats.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/nats.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/nats/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/nats/README.md
 -->
 
 

content/en/docs/v1.0/applications/openbao.md

@@ -7,7 +7,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/openbao.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/openbao/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/openbao/README.md
 -->
 
 

content/en/docs/v1.0/applications/postgres.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/postgres.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/postgres/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/postgres/README.md
 -->
 
 

content/en/docs/v1.0/applications/qdrant.md

@@ -7,7 +7,7 @@ weight: 50
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/qdrant.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/qdrant/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/qdrant/README.md
 -->
 
 

content/en/docs/v1.0/applications/rabbitmq.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/rabbitmq.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/rabbitmq/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/rabbitmq/README.md
 -->
 
 

content/en/docs/v1.0/applications/redis.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/redis.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/redis/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/redis/README.md
 -->
 
 

content/en/docs/v1.0/applications/tenant.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/applications/_include/tenant.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/tenant/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/tenant/README.md
 -->
 
 

content/en/docs/v1.0/kubernetes/_index.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/kubernetes/_include/_index.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/kubernetes/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/kubernetes/README.md
 -->
 
 

content/en/docs/v1.0/networking/http-cache.md

@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/http-cache.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/http-cache/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/http-cache/README.md
 -->
 
 

content/en/docs/v1.0/networking/tcp-balancer.md

@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/tcp-balancer.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/tcp-balancer/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/tcp-balancer/README.md
 -->
 
 

content/en/docs/v1.0/networking/vpc.md

@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/vpc.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vpc/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vpc/README.md
 -->
 
 

content/en/docs/v1.0/networking/vpn.md

@@ -11,7 +11,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/networking/_include/vpn.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vpn/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vpn/README.md
 -->
 
 

content/en/docs/v1.0/operations/services/bootbox.md

@@ -6,7 +6,7 @@ linkTitle: "BootBox"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/bootbox.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/bootbox/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/bootbox/README.md
 -->
 
 

content/en/docs/v1.0/operations/services/etcd.md

@@ -6,7 +6,7 @@ linkTitle: "Etcd"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/etcd.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/etcd/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/etcd/README.md
 -->
 
 

content/en/docs/v1.0/operations/services/ingress.md

@@ -6,7 +6,7 @@ linkTitle: "Ingress"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/ingress.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/ingress/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/ingress/README.md
 -->
 
 

content/en/docs/v1.0/operations/services/monitoring/parameters.md

@@ -7,7 +7,7 @@ weight: 1
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/parameters.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/monitoring/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/monitoring/README.md
 -->
 
 

content/en/docs/v1.0/operations/services/seaweedfs.md

@@ -6,7 +6,7 @@ linkTitle: "SeaweedFS"
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/operations/services/_include/seaweedfs.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/extra/seaweedfs/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/extra/seaweedfs/README.md
 -->
 
 

content/en/docs/v1.0/virtualization/vm-disk.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/virtualization/_include/vm-disk.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vm-disk/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vm-disk/README.md
 -->
 
 

content/en/docs/v1.0/virtualization/vm-instance.md

@@ -10,7 +10,7 @@ aliases:
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/cozystack/website/blob/main/content/en/docs/v1.0/virtualization/_include/vm-instance.md
-source: https://github.com/cozystack/cozystack/blob/release-1.2.1/packages/apps/vm-instance/README.md
+source: https://github.com/cozystack/cozystack/blob/release-1.0/packages/apps/vm-instance/README.md
 -->
 
 

hack/update_apps.sh

@@ -6,12 +6,15 @@ usage() {
 Usage: hack/update_apps.sh [OPTIONS]
 
 Options:
-  --branch BRANCH   Git branch in cozystack/cozystack (default: main)
-  --apps  LIST      Space- or comma-separated list of apps to update
-  --dest  PATH      Destination directory to write the *.md files to
-  --pkgdir DIR      Subdirectory under packages/ to fetch from (default: apps). Examples: apps, extra
-  --index           Write each app into path/<app>/_index.md instead of path/<app>.md (creates subdirectory)
-  -h, --help        Show this help and exit
+  --branch BRANCH       Git ref in cozystack/cozystack used to FETCH README content (default: main)
+  --source-ref REF      Git ref written into the displayed `source:` URL inside generated files.
+                        Defaults to --branch if omitted. Use a stable ref (e.g., release-1.2) to
+                        avoid flipping the source URL on every patch release.
+  --apps  LIST          Space- or comma-separated list of apps to update
+  --dest  PATH          Destination directory to write the *.md files to
+  --pkgdir DIR          Subdirectory under packages/ to fetch from (default: apps). Examples: apps, extra
+  --index               Write each app into path/<app>/_index.md instead of path/<app>.md (creates subdirectory)
+  -h, --help            Show this help and exit
 
 Notes:
   * Template markdown files are expected in DEST_DIR/_include (derived automatically).
@@ -24,6 +27,7 @@ EOF
 }
 
 BRANCH="main"
+SOURCE_REF=""
 DEST_DIR=""
 APPS=()
 INDEX_MODE="false"
@@ -34,6 +38,8 @@ while [[ $# -gt 0 ]]; do
   case "$1" in
     --branch)
       BRANCH="$2"; shift 2 ;;
+    --source-ref)
+      SOURCE_REF="$2"; shift 2 ;;
     --apps)
       IFS=', ' read -r -a APPS <<< "$2"; shift 2 ;;
     --dest)
@@ -69,6 +75,9 @@ fi
 # Derive templates location: DEST_DIR/_include
 SRC_DIR="${DEST_DIR%/}/_include"
 
+# If --source-ref wasn't given, fall back to the fetch branch (preserves prior behavior)
+SOURCE_REF="${SOURCE_REF:-$BRANCH}"
+
 DOCS_REPO="cozystack/website"
 SOURCE_REPO="cozystack/cozystack"
 RAW_BASE_URL="https://raw.githubusercontent.com/${SOURCE_REPO}/${BRANCH}/packages/${PKG_DIR}"
@@ -100,7 +109,7 @@ for app in "${APPS[@]}"; do
 <!--
 Autogenerated content. Don't edit this file directly; edit sources instead.
 metadata: https://github.com/${DOCS_REPO}/blob/main/${rel_template_path}
-source: https://github.com/${SOURCE_REPO}/blob/${BRANCH}/packages/${PKG_DIR}/${app}/README.md
+source: https://github.com/${SOURCE_REPO}/blob/${SOURCE_REF}/packages/${PKG_DIR}/${app}/README.md
 -->
 
 EOF