project-auto-wizard 0.12.2 → 0.13.0

package/payload/workflows/common/PROJECT-COMMON-RELEASE-PUBLISH.yaml

@@ -18,8 +18,8 @@
 #   CHANGELOG.json / CHANGELOG.md, and commits everything back with
 #   [skip ci]. Same as pr-flow's AUTO-CHANGELOG-CONTROL:
 #   - If version.yml metadata.template.options.semver_auto is true
-#     (default): classifies commits (feat -> minor, `!` marker -> major,
-#     else patch; AI-assisted patch->minor upgrade for unclassified
+#     (default): classifies commits (feat -> minor, `!` marker or a
+#     `BREAKING CHANGE:` body footer -> major, else patch; AI-assisted patch->minor upgrade for unclassified
 #     commits) and bumps accordingly.
 #   - Otherwise: always patch+1 (legacy behavior).
 #
@@ -27,7 +27,13 @@
 # release checked separately so a half-published release can be finished
 # on re-run), tag push, release notes = changelog export (ai_notes) +
 # GitHub generate-notes API (contributors/compare links), then
-# gh release create.
+# gh release create, then a workflow_dispatch of README-VERSION-UPDATE
+# (bot-token pushes never wake it, so the README would stay behind).
+# pr-flow only: when the release PR was merged by the bot token (no
+# WORKFLOW_PAT), the merge push woke none of the {{MAIN_BRANCH}} deploy
+# workflows either, so every installed workflow with a {{MAIN_BRANCH}} push
+# trigger and workflow_dispatch is dispatched too. A PAT or human merge
+# already fired the push event, so those are left alone (no double deploy).
 #
 # Release-confirm pattern: "chore(release):" — keep in sync with
 # PROJECT-COMMON-AUTO-CHANGELOG-CONTROL and PROJECT-COMMON-VERSION-CONTROL.
@@ -56,8 +62,16 @@ on:
 
 permissions:
   contents: write
+  # README-VERSION-UPDATE·배포 워크플로우를 workflow_dispatch로 깨운다
+  actions: write
+  # 릴리스 PR을 누가 병합했는지 읽어 배포를 다시 깨울지 정한다
+  pull-requests: read
   copilot-requests: write
 
+env:
+  # 스크립트 import가 .github/scripts/__pycache__를 만들어 봇 커밋에 섞이지 않게 한다
+  PYTHONDONTWRITEBYTECODE: "1"
+
 jobs:
   release:
     name: Tag and publish GitHub Release
@@ -208,13 +222,17 @@ jobs:
           LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
           if [ -n "$LAST_TAG" ]; then
             echo "collecting commits since $LAST_TAG"
-            git log --pretty=%s "${LAST_TAG}..HEAD" > commits.txt
+            LOG_RANGE="${LAST_TAG}..HEAD"
             DIFF_BASE="$LAST_TAG"
           else
             echo "no previous tag — collecting the full history"
-            git log --pretty=%s > commits.txt
+            LOG_RANGE="HEAD"
             DIFF_BASE="4b825dc642cb6eb9a060e54bf8d69288fbee4904" # git empty tree hash
           fi
+          git log --pretty=%s "$LOG_RANGE" > commits.txt
+          # 본문 푸터 BREAKING CHANGE:는 제목 목록 뒤에 한 줄씩 덧붙인다 — 스크립트는 한 줄을
+          # 한 항목으로 읽으므로 본문 전체(%B)를 넣으면 설명 줄까지 변경 항목으로 잡힌다.
+          git log --pretty=%b "$LOG_RANGE" | grep -E '^BREAKING[ -]CHANGE[[:space:]]*:' >> commits.txt || true
           git diff --stat "${DIFF_BASE}..HEAD" > _full_diff_stat.txt
           if [ "$(wc -l < _full_diff_stat.txt)" -gt 49 ]; then
             { head -49 _full_diff_stat.txt; tail -1 _full_diff_stat.txt; } > diff_stat.txt
@@ -263,7 +281,11 @@ jobs:
 
           rm -f pr_body.md summary.md commits.txt diff_stat.txt
 
-          git add -A
+          # -A는 러너가 만든 임시 파일·캐시까지 사용자 레포에 커밋한다.
+          # 버전 파일은 이미 추적 중이라 -u로 충분하고, 첫 릴리스에 새로 생기는
+          # CHANGELOG만 따로 올린다 (.gitignore에 있으면 건너뛴다).
+          git add -u
+          git ls-files -z --others --exclude-standard -- CHANGELOG.json CHANGELOG.md | xargs -0 -r git add --
           if git diff --staged --quiet; then
             echo "no changes to commit"
           else
@@ -386,3 +408,195 @@ jobs:
           VERSION="${{ steps.version.outputs.version }}"
           gh release create "v$VERSION" --title "v$VERSION" --notes-file notes.md
           echo "GitHub Release v$VERSION published"
+
+      - name: Trigger README-VERSION-UPDATE
+        # 봇 토큰(GITHUB_TOKEN)이 만든 push는 README 갱신 워크플로우를 깨우지 못한다 —
+        # PAT 없는 릴리스 PR 병합, 안전망·trunk-based의 [skip ci] 버전 커밋이 그렇다.
+        # 릴리스를 새로 발행했을 때 확정된 버전으로 한 번 직접 깨운다 (중복 실행돼도 변경 없으면 커밋 안 함).
+        if: steps.gate.outputs.proceed == 'true' && steps.version.outputs.release_exists != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh workflow run PROJECT-COMMON-README-VERSION-UPDATE.yaml --ref {{MAIN_BRANCH}}; then
+            echo "README-VERSION-UPDATE workflow_dispatch 트리거 요청 완료"
+          else
+            echo "::notice::README-VERSION-UPDATE 워크플로우를 깨우지 못했습니다 (삭제했거나 비활성화됨) — README 버전 갱신을 건너뜁니다"
+          fi
+
+      - name: Trigger deploy workflows
+        # 봇 토큰(GITHUB_TOKEN)이 병합한 릴리스 PR의 push는 {{MAIN_BRANCH}}의 배포 워크플로우(on: push)를
+        # 깨우지 못한다 — PAT 없는 기본 설치에서 서버·스토어 배포가 한 번도 돌지 않는다.
+        # 그런 병합일 때만 배포 워크플로우를 workflow_dispatch로 직접 깨운다. PAT·사람이 병합했다면
+        # push 이벤트로 이미 실행됐으므로 다시 깨우지 않는다 (중복 배포 방지).
+        # 대상: 마법사가 설치한 워크플로우 중 push.branches에 {{MAIN_BRANCH}}가 있고 workflow_dispatch가
+        # 있는 것. 모노레포 paths 필터는 push와 같은 범위(병합 커밋의 변경 파일)로 평가한다.
+        if: >-
+          steps.gate.outputs.proceed == 'true' &&
+          steps.version.outputs.release_exists != 'true' &&
+          steps.mode.outputs.mode == 'pr-flow'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HAS_WORKFLOW_PAT: ${{ secrets.WORKFLOW_PAT != '' }}
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+          MAIN_BRANCH: "{{MAIN_BRANCH}}"
+        run: |
+          # 이 버전의 릴리스 PR 병합 커밋 — 안전망 bump·수동 재발행처럼 병합이 아닌 릴리스는
+          # 사람의 push가 이미 배포를 깨웠으므로 건너뛴다.
+          MERGE_LINE=$(git log --first-parent --pretty='%H %s' -n 100 | grep -m1 -F " chore(release): v${RELEASE_VERSION} (PR #" || true)
+          if [ -z "$MERGE_LINE" ]; then
+            echo "v${RELEASE_VERSION}은 릴리스 PR 병합으로 들어온 릴리스가 아닙니다 — 배포는 push 이벤트가 맡습니다"
+            exit 0
+          fi
+          MERGE_SHA=${MERGE_LINE%% *}
+          PR_NUMBER=$(printf '%s\n' "$MERGE_LINE" | sed -n 's/.*(PR #\([0-9][0-9]*\)).*/\1/p')
+
+          # 병합 주체로 push 이벤트가 떴는지 판정한다. 조회에 실패하면 PAT 등록 여부로 대신 판단한다.
+          MERGED_BY=""
+          if [ -n "$PR_NUMBER" ]; then
+            MERGED_BY=$(gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" --jq '.merged_by.login // ""' 2>/dev/null || true)
+          fi
+          case "$MERGED_BY" in
+            # GITHUB_TOKEN 병합자는 정확히 이 로그인이다 — 접두사만 같은 다른 계정은 사람 병합으로 본다
+            "github-actions[bot]") echo "PR #${PR_NUMBER}을 봇 토큰이 병합했습니다 — push 이벤트가 배포를 깨우지 못했습니다" ;;
+            "")
+              if [ "$HAS_WORKFLOW_PAT" = "true" ]; then
+                echo "병합 주체를 확인하지 못했고 WORKFLOW_PAT이 있습니다 — push 이벤트가 배포를 실행했다고 보고 건너뜁니다"
+                exit 0
+              fi
+              echo "병합 주체를 확인하지 못했고 WORKFLOW_PAT이 없습니다 — 봇 토큰 병합으로 봅니다"
+              ;;
+            *)
+              echo "PR #${PR_NUMBER}을 ${MERGED_BY}이(가) 병합했습니다 — push 이벤트가 배포를 이미 실행했으므로 건너뜁니다"
+              exit 0
+              ;;
+          esac
+
+          CHANGED_FILES="${RUNNER_TEMP:-/tmp}/release_changed_files.txt"
+          git diff --name-only "${MERGE_SHA}^1" "$MERGE_SHA" > "$CHANGED_FILES" || rm -f "$CHANGED_FILES"
+          export CHANGED_FILES
+
+          # 명령 치환 안의 heredoc은 따옴표 해석이 어긋나므로 파일로 먼저 쓴다
+          FIND_DEPLOY="${RUNNER_TEMP:-/tmp}/find_deploy_workflows.py"
+          cat > "$FIND_DEPLOY" <<'PY'
+          import os, re
+
+          MARKER = "project-auto-wizard:managed-workflow"
+          BRANCH = os.environ["MAIN_BRANCH"]
+          CHANGED = None
+          if os.path.exists(os.environ.get("CHANGED_FILES", "")):
+              with open(os.environ["CHANGED_FILES"], encoding="utf-8") as f:
+                  CHANGED = [l.strip() for l in f if l.strip()]
+
+          # YAML 라이브러리 없이 on 블록만 읽는다 — 러너 파이썬에 PyYAML이 있다고 가정하지 않는다.
+          def strip_comment(s):
+              q = None
+              for i, c in enumerate(s):
+                  if q:
+                      q = None if c == q else q
+                  elif c in "\"'":
+                      q = c
+                  elif c == "#" and (i == 0 or s[i - 1] in " \t"):
+                      return s[:i].rstrip()
+              return s.rstrip()
+
+          def unquote(v):
+              v = v.strip()
+              return v[1:-1] if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'" else v
+
+          # GitHub 필터 문법: ** 는 / 포함 전부, * 와 ? 는 / 를 넘지 않는다. ! 는 뒤 패턴이 앞을 뒤집는다.
+          def glob_re(p):
+              out, i = "", 0
+              while i < len(p):
+                  if p.startswith("**", i):
+                      out, i = out + ".*", i + 2
+                  elif p[i] in "*?":
+                      out, i = out + ("[^/]*" if p[i] == "*" else "[^/]"), i + 1
+                  else:
+                      out, i = out + re.escape(p[i]), i + 1
+              return re.compile(out + r"\Z")
+
+          def matches(pats, value):
+              hit = False
+              for p in pats:
+                  neg = p.startswith("!")
+                  if glob_re(p[1:] if neg else p).match(value):
+                      hit = not neg
+              return hit
+
+          def mapping(lines):
+              if not lines:
+                  return {}
+              base = min(i for i, _ in lines)
+              res = {}
+              for n, (ind, text) in enumerate(lines):
+                  m = re.match(r"""^["']?([\w-]+)["']?\s*:(?:\s+(.*))?$""", text)
+                  if ind != base or text.startswith("- ") or not m:
+                      continue
+                  sub = []
+                  for ind2, text2 in lines[n + 1:]:
+                      if ind2 < ind or (ind2 == ind and not text2.startswith("- ")):
+                          break
+                      sub.append((ind2, text2))
+                  res[m.group(1)] = (m.group(2) or "", sub)
+              return res
+
+          def items(entry):
+              inline, sub = entry
+              if inline.startswith("["):
+                  return [unquote(x) for x in inline.strip("[]").split(",") if x.strip()]
+              if inline:
+                  return [unquote(inline)]
+              return [unquote(t[2:]) for _, t in sub if t.startswith("- ")]
+
+          def is_target(path):
+              with open(path, encoding="utf-8") as f:
+                  raw = f.read()
+              if MARKER not in raw:
+                  return False
+              lines = []
+              for l in raw.splitlines():
+                  s = strip_comment(l)
+                  if s.strip():
+                      lines.append((len(s) - len(s.lstrip()), s.strip()))
+              on = mapping(lines).get("on")
+              events = mapping(on[1]) if on else {}
+              push = events.get("push")
+              if "workflow_dispatch" not in events or not push:
+                  return False
+              f = mapping(push[1])
+              if "branches" not in f or not matches(items(f["branches"]), BRANCH):
+                  return False
+              if CHANGED is not None:
+                  if "paths" in f and not any(matches(items(f["paths"]), c) for c in CHANGED):
+                      return False
+                  if "paths-ignore" in f and all(matches(items(f["paths-ignore"]), c) for c in CHANGED):
+                      return False
+              return True
+
+          root = ".github/workflows"
+          for name in sorted(os.listdir(root)) if os.path.isdir(root) else []:
+              # 공통 워크플로우(릴리스·README·안전망)는 배포가 아니고, 필요한 것은 각자 따로 깨운다
+              if name.startswith("PROJECT-COMMON-") or not re.search(r"\.ya?ml$", name):
+                  continue
+              if is_target(os.path.join(root, name)):
+                  print(name)
+          PY
+          TARGETS=$(python3 "$FIND_DEPLOY")
+
+          if [ -z "$TARGETS" ]; then
+            echo "{{MAIN_BRANCH}} push로 도는 배포 워크플로우가 없습니다 — 건너뜁니다"
+            exit 0
+          fi
+
+          FAILED=0
+          for WF in $TARGETS; do
+            # 입력 없이 실행하면 workflow_dispatch 입력 기본값(설치 때 고른 배포 모드 등)을 쓴다
+            if gh workflow run "$WF" --ref {{MAIN_BRANCH}}; then
+              echo "$WF workflow_dispatch 트리거 요청 완료"
+            else
+              FAILED=1
+              echo "::warning::$WF 배포 워크플로우를 깨우지 못했습니다 — Actions 탭에서 Run workflow로 직접 실행하세요"
+            fi
+          done
+          exit "$FAILED"

package/payload/workflows/common/PROJECT-COMMON-VERSION-CONTROL.yaml

@@ -4,7 +4,9 @@
 #
 # [Safety net] Only when a direct push (one that did not go through a
 # release PR) lands on {{MAIN_BRANCH}} (production), this workflow bumps
-# the patch version and syncs every version file.
+# the patch version, syncs every version file, and adds a CHANGELOG entry
+# built from the commits since the last release tag (these become the
+# release notes RELEASE-PUBLISH publishes).
 #
 # Normal releases ({{DEVELOP_BRANCH}} -> {{MAIN_BRANCH}} PR) get their
 # version confirmed by AUTO-CHANGELOG-CONTROL before the merge. The merge
@@ -20,7 +22,9 @@
 #
 # After pushing the safety-net bump, this workflow also triggers
 # RELEASE-PUBLISH via workflow_dispatch so a version drift is
-# auto-recovered instead of requiring a manual re-run.
+# auto-recovered instead of requiring a manual re-run, and merges
+# {{MAIN_BRANCH}} back into {{DEVELOP_BRANCH}} so the next release PR does
+# not conflict on the version files.
 
 name: PROJECT-VERSION-CONTROL
 
@@ -42,6 +46,10 @@ permissions:
   contents: write
   actions: write
 
+env:
+  # 스크립트 import가 .github/scripts/__pycache__를 만들어 봇 커밋에 섞이지 않게 한다
+  PYTHONDONTWRITEBYTECODE: "1"
+
 jobs:
   version-bump:
     name: Safety-net version bump
@@ -130,6 +138,44 @@ jobs:
             echo "version.yml not found"
           fi
 
+      - name: Update CHANGELOG for the safety-net release
+        # 안전망 릴리스도 실제로 들어간 커밋으로 CHANGELOG 항목을 만든다. 항목이 없으면
+        # RELEASE-PUBLISH가 고정 문구로 릴리스 노트를 채우고 변경 내역이 어디에도 남지 않는다.
+        # 요약 엔진: 사용자 API(설정된 경우) -> 규칙 기반 (Copilot은 릴리스 PR·trunk 경로에서만 쓴다)
+        if: steps.release_guard.outputs.skip != 'true'
+        env:
+          AI_API_KEY: ${{ secrets.AI_API_KEY }}
+          AI_API_BASE_URL: ${{ vars.AI_API_BASE_URL }}
+          AI_MODEL: ${{ vars.AI_MODEL }}
+        run: |
+          NEW_VERSION="${{ steps.version.outputs.new_version }}"
+
+          # 마지막 릴리스 태그 이후 {{MAIN_BRANCH}}에 직접 들어온 커밋 (태그가 없으면 전체 이력)
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          LOG_RANGE="${LAST_TAG:+${LAST_TAG}..}HEAD"
+          git log --pretty=%s "$LOG_RANGE" > commits.txt
+          # 본문 푸터 BREAKING CHANGE:는 제목 목록 뒤에 한 줄씩 덧붙인다 — 스크립트는 한 줄을
+          # 한 항목으로 읽으므로 본문 전체(%B)를 넣으면 설명 줄까지 변경 항목으로 잡힌다.
+          git log --pretty=%b "$LOG_RANGE" | grep -E '^BREAKING[ -]CHANGE[[:space:]]*:' >> commits.txt || true
+          echo "commits since ${LAST_TAG:-the beginning}: $(wc -l < commits.txt)"
+
+          python3 .github/scripts/changelog_manager.py ai-summary \
+            --commits-file commits.txt \
+            --version "$NEW_VERSION" \
+            --output summary.md
+
+          # update-from-summary reads ./pr_body.md
+          cp summary.md pr_body.md
+          VERSION="$NEW_VERSION"
+          PROJECT_TYPES="${{ steps.project_info.outputs.project_types }}"
+          TODAY=$(date '+%Y-%m-%d')
+          TIMESTAMP=$(date '+%Y-%m-%dT%H:%M:%SZ')
+          export VERSION PROJECT_TYPES TODAY TIMESTAMP
+          python3 .github/scripts/changelog_manager.py update-from-summary
+          python3 .github/scripts/changelog_manager.py generate-md
+
+          rm -f commits.txt summary.md pr_body.md
+
       - name: Commit and push changes
         id: commit_push
         if: steps.release_guard.outputs.skip != 'true'
@@ -137,7 +183,11 @@ jobs:
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
 
-          git add -A
+          # -A는 러너가 만든 임시 파일·캐시까지 사용자 레포에 커밋한다.
+          # 버전 파일은 이미 추적 중이라 -u로 충분하고, 새로 생기는 CHANGELOG만
+          # 따로 올린다 (.gitignore에 있으면 건너뛴다).
+          git add -u
+          git ls-files -z --others --exclude-standard -- CHANGELOG.json CHANGELOG.md | xargs -0 -r git add --
 
           if git diff --staged --quiet; then
             echo "no changes to commit (already in sync)"
@@ -192,6 +242,42 @@ jobs:
           gh workflow run PROJECT-COMMON-RELEASE-PUBLISH.yaml --ref {{MAIN_BRANCH}}
           echo "RELEASE-PUBLISH workflow_dispatch 트리거 요청 완료 (WORKFLOW_PAT 없이도 동작, 이슈 #61 드리프트 자동 복구)"
 
+      - name: Back-merge the safety-net bump into {{DEVELOP_BRANCH}}
+        # 안전망 bump는 {{MAIN_BRANCH}}에만 올라간다. {{DEVELOP_BRANCH}}가 이를 모르면 다음 릴리스 PR에서
+        # 양쪽이 같은 버전 줄을 고쳐 충돌하므로 곧바로 {{DEVELOP_BRANCH}}에도 병합해 둔다.
+        # 실패(충돌·브랜치 보호)해도 안전망 릴리스는 이미 끝났으므로 경고만 남긴다.
+        if: steps.release_guard.outputs.skip != 'true' && steps.commit_push.outputs.pushed == 'true'
+        run: |
+          DEVELOP_BRANCH="{{DEVELOP_BRANCH}}"
+          NEW_VERSION="${{ steps.version.outputs.new_version }}"
+          MANUAL="git checkout $DEVELOP_BRANCH && git pull && git merge origin/{{MAIN_BRANCH}} && git push"
+
+          if ! git ls-remote --exit-code --heads origin "$DEVELOP_BRANCH" >/dev/null 2>&1; then
+            echo "branch $DEVELOP_BRANCH not found — nothing to back-merge"
+            exit 0
+          fi
+
+          for ATTEMPT in 1 2 3; do
+            git fetch -q origin "$DEVELOP_BRANCH" {{MAIN_BRANCH}}
+            git checkout -q -B safety-net-back-merge "origin/$DEVELOP_BRANCH"
+            if git merge-base --is-ancestor "origin/{{MAIN_BRANCH}}" HEAD; then
+              echo "$DEVELOP_BRANCH already contains {{MAIN_BRANCH}}"
+              exit 0
+            fi
+            if ! git merge --no-edit -m "chore(version): merge v${NEW_VERSION} safety-net bump into ${DEVELOP_BRANCH} [skip ci]" "origin/{{MAIN_BRANCH}}"; then
+              git merge --abort 2>/dev/null || true
+              echo "::warning::{{MAIN_BRANCH}}을 ${DEVELOP_BRANCH}에 자동 병합하지 못했습니다 (충돌). 다음 릴리스 PR 전에 직접 병합하세요: $MANUAL"
+              exit 0
+            fi
+            if git push origin "HEAD:$DEVELOP_BRANCH"; then
+              echo "safety-net bump v$NEW_VERSION merged into $DEVELOP_BRANCH"
+              exit 0
+            fi
+            echo "push attempt $ATTEMPT failed — retrying"
+            sleep 5
+          done
+          echo "::warning::${DEVELOP_BRANCH}에 push하지 못했습니다 (브랜치 보호 등). 다음 릴리스 PR 전에 직접 병합하세요: $MANUAL"
+
       - name: Summary
         if: always()
         run: |

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-FIREBASE-CICD.yaml

@@ -20,14 +20,14 @@
 #
 # 환경 설정 (선택):
 # ENV_FILE 또는 ENV: .env 파일 내용 (둘 중 하나, ENV_FILE 우선)
-# GOOGLE_SERVICES_JSON: Firebase google-services.json
+# GOOGLE_SERVICES_JSON (선택): Firebase google-services.json
 #
 # ※ 위 Secrets는 저장소 Settings → Secrets and variables → Actions에 등록하세요.
 #    FIREBASE_APP_ID·FIREBASE_TESTER_GROUP은 아래 env 섹션 값을 직접 수정합니다.
 #
 # 프로젝트별 설정 (env 섹션에서 수정)
 # APP_ARTIFACT_NAME       : 프로젝트 이름
-# FLUTTER_VERSION    : Flutter SDK 버전
+# FLUTTER_VERSION    : Flutter SDK 버전 (빈 값 = stable 최신)
 # JAVA_VERSION       : Java 버전
 # FIREBASE_APP_ID    : Firebase 앱 ID (Firebase Console에서 확인)
 # FIREBASE_TESTER_GROUP : Firebase 테스터 그룹명
@@ -51,7 +51,9 @@ env:
   # 프로젝트 이름
   APP_ARTIFACT_NAME: "__APP_ARTIFACT_NAME__"  # @wizard ask:@repo
   # Flutter/Java 버전
-  FLUTTER_VERSION: "3.35.5"
+  # Flutter SDK 버전 — 비워 두면 stable 채널 최신을 쓴다(최신 flutter create 프로젝트의 SDK 제약과 맞음).
+  # 특정 버전에 고정하려면 "3.38.9"처럼 적는다. pubspec.yaml의 environment.sdk 범위를 만족해야 한다.
+  FLUTTER_VERSION: ""
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
   PROJECT_TYPE: "flutter"
   # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등 — 설치 시 자동 설정
@@ -81,11 +83,40 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
-          ref: main
+          ref: "{{MAIN_BRANCH}}"
           fetch-depth: 0
 
+      # 서명·업로드 Secret이 없으면 빌드를 한참 진행한 뒤에야 실패하므로, 빠진 이름을 먼저 모두 알려 주고 멈춘다
+      # ENV_FILE·GOOGLE_SERVICES_JSON은 선택이라 점검하지 않는다
+      - name: 배포 사전 점검 (Secret)
+        env:
+          RELEASE_KEYSTORE_BASE64: ${{ secrets.RELEASE_KEYSTORE_BASE64 }}
+          RELEASE_KEYSTORE_PASSWORD: ${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
+          RELEASE_KEY_ALIAS: ${{ secrets.RELEASE_KEY_ALIAS }}
+          RELEASE_KEY_PASSWORD: ${{ secrets.RELEASE_KEY_PASSWORD }}
+          FIREBASE_SERVICE_ACCOUNT_JSON_BASE64: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_JSON_BASE64 }}
+        run: |
+          MISSING=""
+          for NAME in RELEASE_KEYSTORE_BASE64 RELEASE_KEYSTORE_PASSWORD RELEASE_KEY_ALIAS RELEASE_KEY_PASSWORD FIREBASE_SERVICE_ACCOUNT_JSON_BASE64; do
+            [ -n "${!NAME}" ] || MISSING="$MISSING $NAME"
+          done
+          FAILED=false
+          if [ -n "$MISSING" ]; then
+            echo "::error title=필수 Secret 누락::등록되지 않은 GitHub Secret:$MISSING — Settings → Secrets and variables → Actions에서 등록하세요"
+            FAILED=true
+          fi
+          # 업로드 대상 앱 ID는 Secret이 아니라 이 파일 env 섹션 값이다
+          if [ -z "$FIREBASE_APP_ID" ] || [ "$FIREBASE_APP_ID" = "your-firebase-app-id" ]; then
+            echo "::error title=FIREBASE_APP_ID 미설정::워크플로우 env 섹션의 FIREBASE_APP_ID를 Firebase Console의 앱 ID로 바꾸세요"
+            FAILED=true
+          fi
+          if [ "$FAILED" = "true" ]; then
+            exit 1
+          fi
+          echo "✅ 사전 점검 통과: 필수 Secret과 FIREBASE_APP_ID가 모두 있습니다"
+
       - name: Pull latest changes
-        run: git pull origin main
+        run: git pull origin {{MAIN_BRANCH}}
 
       - name: Prepare env file
         env:
@@ -104,6 +135,7 @@ jobs:
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -211,11 +243,11 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
-          ref: main
+          ref: "{{MAIN_BRANCH}}"
           fetch-depth: 0
 
       - name: Pull latest changes
-        run: git pull origin main
+        run: git pull origin {{MAIN_BRANCH}}
 
       - name: Download project files
         uses: actions/download-artifact@v8
@@ -239,9 +271,27 @@ jobs:
           fi
 
       - name: Setup Release Keystore
+        env:
+          RELEASE_KEYSTORE_BASE64: ${{ secrets.RELEASE_KEYSTORE_BASE64 }}
+          RELEASE_KEYSTORE_PASSWORD: ${{ secrets.RELEASE_KEYSTORE_PASSWORD }}
+          RELEASE_KEY_ALIAS: ${{ secrets.RELEASE_KEY_ALIAS }}
+          RELEASE_KEY_PASSWORD: ${{ secrets.RELEASE_KEY_PASSWORD }}
         run: |
+          # 빈 Secret으로 빈 keystore를 만들면 어떤 키로 서명됐는지 알 수 없거나 뒤 단계에서 엉뚱한 오류로 끝난다
+          MISSING=""
+          for name in RELEASE_KEYSTORE_BASE64 RELEASE_KEYSTORE_PASSWORD RELEASE_KEY_ALIAS RELEASE_KEY_PASSWORD; do
+            [ -n "${!name}" ] || MISSING="$MISSING $name"
+          done
+          if [ -n "$MISSING" ]; then
+            echo "::error::서명 Secret이 비어 있습니다:$MISSING (워크플로우 상단 주석 참고)"
+            exit 1
+          fi
           mkdir -p android/app/keystore
-          echo "${{ secrets.RELEASE_KEYSTORE_BASE64 }}" | base64 -d > android/app/keystore/key.jks
+          printf '%s' "$RELEASE_KEYSTORE_BASE64" | base64 -d > android/app/keystore/key.jks
+          if [ ! -s android/app/keystore/key.jks ]; then
+            echo "::error::RELEASE_KEYSTORE_BASE64를 디코딩한 keystore가 비어 있습니다"
+            exit 1
+          fi
           echo "✅ Release Keystore 생성 완료"
           ls -la android/app/keystore/
 
@@ -254,18 +304,24 @@ jobs:
           keyPassword=${{ secrets.RELEASE_KEY_PASSWORD }}
           EOF
           echo "✅ key.properties 생성 완료"
-          cat android/key.properties
 
-      - name: Create Google-services.json
+      # google-services.json 생성 (선택) — 비어 있으면 빈 파일을 만들지 않는다
+      - name: Create google-services.json
+        env:
+          GOOGLE_SERVICES_JSON: ${{ secrets.GOOGLE_SERVICES_JSON }}
         run: |
-          cat << 'EOF' > android/app/google-services.json
-          ${{ secrets.GOOGLE_SERVICES_JSON }}
-          EOF
-          echo "✅ Google-services.json 생성 완료"
+          if [ -n "$GOOGLE_SERVICES_JSON" ]; then
+            mkdir -p android/app
+            printf '%s' "$GOOGLE_SERVICES_JSON" > android/app/google-services.json
+            echo "✅ google-services.json created"
+          else
+            echo "ℹ️ GOOGLE_SERVICES_JSON secret not provided, skipping"
+          fi
 
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
         with:
+          channel: stable
           flutter-version: ${{ env.FLUTTER_VERSION }}
           cache: true
 
@@ -542,7 +598,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
         with:
-          ref: main
+          ref: "{{MAIN_BRANCH}}"
           fetch-depth: 0
 
       - name: Download AAB artifact
@@ -558,8 +614,14 @@ jobs:
           path: .
 
       - name: Setup Firebase credentials file
+        env:
+          SERVICE_ACCOUNT_BASE64: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_JSON_BASE64 }}
         run: |
-          echo "${{ secrets.FIREBASE_SERVICE_ACCOUNT_JSON_BASE64 }}" | base64 --decode > firebase-service-account.json
+          if [ -z "$SERVICE_ACCOUNT_BASE64" ]; then
+            echo "::error::FIREBASE_SERVICE_ACCOUNT_JSON_BASE64 Secret이 비어 있습니다"
+            exit 1
+          fi
+          printf '%s' "$SERVICE_ACCOUNT_BASE64" | base64 --decode > firebase-service-account.json
           echo "✅ Firebase 서비스 계정 JSON 파일 생성 완료"
 
       # Firebase App Distribution release notes 길이 제한 (안전망)