feat(ci): Add branch-aware tagging and retention policy docs

Tagging Strategy:
- main branch: {sha} + 'latest'
- develop branch: {sha} + 'dev'
- git tags: {sha} + version (e.g., v1.0.0)

Also added docs/harbor-tag-retention-policy.md with:
- Recommended retention rules for Harbor
- Garbage collection schedule
- Cleanup commands and scripts
- Monitoring commands

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.woodpecker.yml

@@ -9,6 +9,10 @@ variables:
     pnpm install --frozen-lockfile
   - &use_deps |
     corepack enable
+  # Kaniko base command setup
+  - &kaniko_setup |
+    mkdir -p /kaniko/.docker
+    echo "{\"auths\":{\"reg.mosaicstack.dev\":{\"username\":\"$HARBOR_USER\",\"password\":\"$HARBOR_PASS\"}}}" > /kaniko/.docker/config.json
 
 steps:
   install:
@@ -83,6 +87,12 @@ steps:
   # Docker Build & Push (main/develop only)
   # ======================
   # Requires secrets: harbor_username, harbor_password
+  #
+  # Tagging Strategy:
+  #   - Always: commit SHA (e.g., 658ec077)
+  #   - main branch: 'latest'
+  #   - develop branch: 'dev'
+  #   - git tags: version tag (e.g., v1.0.0)
 
   # Build and push API image using Kaniko
   docker-build-api:
@@ -92,13 +102,25 @@ steps:
         from_secret: harbor_username
       HARBOR_PASS:
         from_secret: harbor_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
     commands:
-      - mkdir -p /kaniko/.docker
-      - echo "{\"auths\":{\"reg.mosaicstack.dev\":{\"username\":\"$HARBOR_USER\",\"password\":\"$HARBOR_PASS\"}}}" > /kaniko/.docker/config.json
-      - /kaniko/executor --context . --dockerfile apps/api/Dockerfile --destination reg.mosaicstack.dev/mosaic/api:${CI_COMMIT_SHA:0:8} --destination reg.mosaicstack.dev/mosaic/api:latest
+      - *kaniko_setup
+      - |
+        DESTINATIONS="--destination reg.mosaicstack.dev/mosaic/api:${CI_COMMIT_SHA:0:8}"
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/api:latest"
+        elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/api:dev"
+        fi
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/api:$CI_COMMIT_TAG"
+        fi
+        /kaniko/executor --context . --dockerfile apps/api/Dockerfile $DESTINATIONS
     when:
       - branch: [main, develop]
-        event: [push, manual]
+        event: [push, manual, tag]
     depends_on:
       - build
 
@@ -110,13 +132,25 @@ steps:
         from_secret: harbor_username
       HARBOR_PASS:
         from_secret: harbor_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
     commands:
-      - mkdir -p /kaniko/.docker
-      - echo "{\"auths\":{\"reg.mosaicstack.dev\":{\"username\":\"$HARBOR_USER\",\"password\":\"$HARBOR_PASS\"}}}" > /kaniko/.docker/config.json
-      - /kaniko/executor --context . --dockerfile apps/web/Dockerfile --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev --destination reg.mosaicstack.dev/mosaic/web:${CI_COMMIT_SHA:0:8} --destination reg.mosaicstack.dev/mosaic/web:latest
+      - *kaniko_setup
+      - |
+        DESTINATIONS="--destination reg.mosaicstack.dev/mosaic/web:${CI_COMMIT_SHA:0:8}"
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/web:latest"
+        elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/web:dev"
+        fi
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/web:$CI_COMMIT_TAG"
+        fi
+        /kaniko/executor --context . --dockerfile apps/web/Dockerfile --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev $DESTINATIONS
     when:
       - branch: [main, develop]
-        event: [push, manual]
+        event: [push, manual, tag]
     depends_on:
       - build
 
@@ -128,12 +162,24 @@ steps:
         from_secret: harbor_username
       HARBOR_PASS:
         from_secret: harbor_password
+      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
+      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
+      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
     commands:
-      - mkdir -p /kaniko/.docker
-      - echo "{\"auths\":{\"reg.mosaicstack.dev\":{\"username\":\"$HARBOR_USER\",\"password\":\"$HARBOR_PASS\"}}}" > /kaniko/.docker/config.json
-      - /kaniko/executor --context docker/postgres --dockerfile docker/postgres/Dockerfile --destination reg.mosaicstack.dev/mosaic/postgres:${CI_COMMIT_SHA:0:8} --destination reg.mosaicstack.dev/mosaic/postgres:latest
+      - *kaniko_setup
+      - |
+        DESTINATIONS="--destination reg.mosaicstack.dev/mosaic/postgres:${CI_COMMIT_SHA:0:8}"
+        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/postgres:latest"
+        elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/postgres:dev"
+        fi
+        if [ -n "$CI_COMMIT_TAG" ]; then
+          DESTINATIONS="$DESTINATIONS --destination reg.mosaicstack.dev/mosaic/postgres:$CI_COMMIT_TAG"
+        fi
+        /kaniko/executor --context docker/postgres --dockerfile docker/postgres/Dockerfile $DESTINATIONS
     when:
       - branch: [main, develop]
-        event: [push, manual]
+        event: [push, manual, tag]
     depends_on:
       - build