project-auto-wizard 0.10.0 → 0.12.0

package/payload/scripts/changelog_manager.py

@@ -27,7 +27,9 @@ import html
 import json
 import os
 import re
+import subprocess
 import sys
+import tempfile
 import traceback
 import urllib.error
 import urllib.request
@@ -123,7 +125,7 @@ def _parse_markdown_sections(md_content: str) -> dict:
     """
     섹션 파서: `### 카테고리` 헤딩 + `- 항목` 불릿 형식.
 
-    AI 엔진 체인(사용자 지정 API → GitHub Models)과 규칙 기반 폴백이
+    AI 엔진 체인(사용자 지정 API → Copilot CLI)과 규칙 기반 폴백이
     동일하게 생성하는 형식이므로 1순위로 시도한다.
     """
     detected: dict[str, dict] = {}
@@ -389,21 +391,19 @@ def _ai_assisted_minor_upgrade(unclassified_lines: list[str]) -> bool:
         return False
     prompt = _BUMP_AI_PROMPT_PREFIX + "\n".join(f"- {line}" for line in unclassified_lines)
 
-    ai_api_key = os.environ.get('AI_API_KEY')
-    github_token = os.environ.get('GITHUB_TOKEN')
-    candidates = [
-        (ai_api_key, os.environ.get('AI_API_BASE_URL') or _AI_DEFAULT_BASE_URL, os.environ.get('AI_MODEL') or _AI_DEFAULT_MODEL),
-        (github_token, _AI_DEFAULT_BASE_URL, _AI_DEFAULT_MODEL),
-    ]
-    for token, base_url, model in candidates:
-        if not token:
-            continue
+    settings = _user_api_settings()
+    if settings:
+        api_key, base_url, model = settings
         try:
-            response = call_openai_compatible(base_url, token, model, prompt)
-            return response.strip() == 'MINOR'
+            return call_openai_compatible(base_url, api_key, model, prompt).strip() == 'MINOR'
         except Exception as e:
             print(f"[warn] bump AI assist failed: {e}", file=sys.stderr)
-            continue
+
+    if _copilot_enabled():
+        try:
+            return call_copilot_cli(prompt).strip() == 'MINOR'
+        except Exception as e:
+            print(f"[warn] bump AI assist (copilot) failed: {e}", file=sys.stderr)
     return False
 
 
@@ -694,8 +694,67 @@ def cmd_export_release_notes(version: str, output_path: str | None) -> int:
 
 # ------------------------ ai-summary 엔진 체인 ------------------------
 
-_AI_DEFAULT_BASE_URL = "https://models.github.ai/inference"
-_AI_DEFAULT_MODEL = "openai/gpt-4o-mini"
+_COPILOT_DEFAULT_MODEL = "claude-haiku-4.5"
+_COPILOT_TIMEOUT_SECONDS = 90
+
+
+def _user_api_settings() -> tuple[str, str, str] | None:
+    """사용자 지정 AI 티어 설정. AI_API_KEY와 AI_API_BASE_URL, AI_MODEL이 모두 있어야 한다.
+
+    키만 있고 URL·모델이 비어 있으면 그 키를 어디로도 보내지 않고 경고 후 건너뛴다
+    (종료된 기본 엔드포인트으로 사용자 키가 흘러가던 문제 방지)."""
+    api_key = os.environ.get('AI_API_KEY')
+    if not api_key:
+        return None
+    base_url = os.environ.get('AI_API_BASE_URL')
+    model = os.environ.get('AI_MODEL')
+    if not base_url or not model:
+        print(
+            "::warning::AI_API_KEY가 설정됐지만 AI_API_BASE_URL/AI_MODEL이 없어 사용자 API 티어를 건너뜁니다",
+            file=sys.stderr,
+        )
+        return None
+    return api_key, base_url, model
+
+
+def _copilot_enabled() -> bool:
+    """version.yml의 copilot_ai가 켜져 있고(워크플로우가 COPILOT_AI로 전달) 토큰이 있을 때만 True."""
+    return os.environ.get('COPILOT_AI', '').strip().lower() == 'true' and bool(os.environ.get('GITHUB_TOKEN'))
+
+
+def call_copilot_cli(prompt: str) -> str:
+    """Copilot CLI를 텍스트 생성 전용으로 호출해 응답 텍스트를 반환.
+
+    프롬프트에 필요한 정보가 이미 다 들어 있으므로 에이전트 기능은 전부 막는다:
+    빈 임시 디렉터리에서 실행하고, shell/write/url 도구를 거부하며, 내장 MCP와
+    커스텀 지침 로딩을 끈다.
+    실패(비정상 종료·타임아웃·CLI 없음)는 예외로 올려 호출부가 fallback한다."""
+    model = os.environ.get('COPILOT_MODEL') or _COPILOT_DEFAULT_MODEL
+    with tempfile.TemporaryDirectory() as workdir:
+        result = subprocess.run(
+            [
+                'copilot', '-p', prompt, '-s',
+                '--no-ask-user', '--no-color', '--no-custom-instructions', '--disable-builtin-mcps',
+                '--deny-tool=shell', '--deny-tool=write', '--deny-tool=url',
+                '--model', model,
+            ],
+            cwd=workdir, stdin=subprocess.DEVNULL,
+            capture_output=True, text=True, timeout=_COPILOT_TIMEOUT_SECONDS,
+        )
+    if result.returncode != 0:
+        raise RuntimeError(f"copilot exited with {result.returncode}: {result.stderr.strip()[:200]}")
+    return result.stdout
+
+
+def _is_valid_copilot_summary(text: str) -> bool:
+    """프롬프트가 요구한 Markdown 형식인지 최소한만 검사한다.
+
+    섹션 헤딩('### ')이 하나도 없거나 코드펜스로 시작하는(통째로 감싼) 응답은 릴리스 노트로
+    쓰지 않는다."""
+    stripped = text.strip()
+    if not stripped or stripped.startswith('```'):
+        return False
+    return any(line.startswith('### ') for line in stripped.splitlines())
 
 
 def _build_ai_prompt(commit_lines: list[str], pr_title: str | None, version: str, diff_stat: str | None = None) -> str:
@@ -760,16 +819,13 @@ def cmd_ai_summary(commits_file: str, version: str, output_path: str, pr_title:
         except Exception:
             diff_stat = None
 
-    ai_api_key = os.environ.get('AI_API_KEY')
-    ai_base_url = os.environ.get('AI_API_BASE_URL') or _AI_DEFAULT_BASE_URL
-    ai_model = os.environ.get('AI_MODEL') or _AI_DEFAULT_MODEL
-    github_token = os.environ.get('GITHUB_TOKEN')
-
     engine = None
     summary_text = None
     prompt = _build_ai_prompt(commit_lines, pr_title, version, diff_stat)
 
-    if ai_api_key:
+    settings = _user_api_settings()
+    if settings:
+        ai_api_key, ai_base_url, ai_model = settings
         try:
             candidate = call_openai_compatible(ai_base_url, ai_api_key, ai_model, prompt)
             if candidate and candidate.strip():
@@ -780,19 +836,16 @@ def cmd_ai_summary(commits_file: str, version: str, output_path: str, pr_title:
         except Exception as e:
             print(f"[warn] user-api failed: {e}", file=sys.stderr)
 
-    if summary_text is None and github_token:
+    if summary_text is None and _copilot_enabled():
         try:
-            # GitHub Models는 자체 모델 카탈로그만 서빙한다 — 사용자 API용으로
-            # AI_MODEL이 오버라이드돼 있어도 여기서는 기본 모델을 쓴다
-            # (커스텀 모델명은 models.github.ai에서 404).
-            candidate = call_openai_compatible(_AI_DEFAULT_BASE_URL, github_token, _AI_DEFAULT_MODEL, prompt)
-            if candidate and candidate.strip():
+            candidate = call_copilot_cli(prompt)
+            if _is_valid_copilot_summary(candidate):
                 summary_text = candidate
-                engine = "github-models"
+                engine = "copilot"
             else:
-                print("[warn] github-models failed: empty content in response", file=sys.stderr)
+                print("[warn] copilot failed: empty or not in the requested Markdown format", file=sys.stderr)
         except Exception as e:
-            print(f"[warn] github-models failed: {e}", file=sys.stderr)
+            print(f"[warn] copilot failed: {e}", file=sys.stderr)
 
     if summary_text is None:
         classified = classify_commits(commit_lines)

package/payload/version.yml.template

@@ -6,6 +6,9 @@
 #   (default) — feat: commits bump minor, a `!` breaking marker on any commit
 #   type bumps major. Set semver_auto: false to always patch-bump instead
 #   (then edit major/minor manually, e.g., 1.0.5 -> 1.1.0 or 2.0.0).
+# - copilot_ai: opt-in (default false) — true lets the release/PR summary
+#   workflows call GitHub Copilot CLI, which consumes GitHub Copilot AI Credits.
+#   Falls back to rule-based summaries whenever Copilot is off or unavailable.
 # ===
 # Supported project types: spring, flutter, next, react, react-native,
 #                          react-native-expo, node, python, basic, go
@@ -47,5 +50,7 @@ metadata:
       nexus: {{OPT_NEXUS}}
       secret_backup: {{OPT_SECRET_BACKUP}}
       semver_auto: {{OPT_SEMVER_AUTO}}
+      copilot_ai: {{OPT_COPILOT_AI}}
       deploy_style: "{{OPT_DEPLOY_STYLE}}" # simple | nginx | traefik | none (서버 배포 워크플로우)
+{{FLUTTER_OPTIONS}}
 {{DEPLOY}}

package/payload/workflows/common/PROJECT-COMMON-AI-PR-SUMMARY.yaml

@@ -4,9 +4,9 @@
 # Self-hosted AI PR summary bot — no third-party service required.
 # ===================================================================
 #
-# Posts an AI-generated summary comment on PRs targeting the default
-# branch, using the same zero-API-key engine chain as the release
-# changelog (user API key -> GitHub Models -> rule-based fallback).
+# Posts a summary comment on PRs targeting the default branch, using the
+# same engine chain as the release changelog (user API key -> Copilot CLI,
+# opt-in via version.yml copilot_ai -> rule-based fallback).
 # The prompt includes commit subjects plus a capped `git diff --stat`.
 #
 # On release PRs (head branch == {{DEVELOP_BRANCH}}) this job is skipped.
@@ -30,7 +30,11 @@ on:
 permissions:
   contents: read
   pull-requests: write
-  models: read
+  copilot-requests: write
+
+concurrency:
+  group: ai-pr-summary-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
 
 jobs:
   ai-pr-summary:
@@ -46,6 +50,20 @@ jobs:
           fetch-depth: 0
           ref: ${{ github.event.pull_request.head.ref }}
 
+      - name: Read copilot_ai option from version.yml
+        id: copilot_options
+        run: |
+          # scoped to the metadata: -> template: -> options: chain so an
+          # unrelated "copilot_ai:" key can never hijack the value
+          COPILOT_AI=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?options:.*?copilot_ai:\s*\"?(true|false)", t, re.S); print(m.group(1) if m else "false")' 2>/dev/null || echo "false")
+          echo "copilot_ai=$COPILOT_AI" >> $GITHUB_OUTPUT
+          echo "copilot_ai option: $COPILOT_AI"
+
+      - name: Install Copilot CLI
+        if: steps.copilot_options.outputs.copilot_ai == 'true'
+        continue-on-error: true
+        run: npm install -g @github/copilot@1.0.88
+
       - name: Generate and post AI summary
         env:
           PR_TITLE: ${{ github.event.pull_request.title }}
@@ -53,6 +71,8 @@ jobs:
           AI_API_BASE_URL: ${{ vars.AI_API_BASE_URL }}
           AI_MODEL: ${{ vars.AI_MODEL }}
           GITHUB_TOKEN: ${{ github.token }}
+          COPILOT_AI: ${{ steps.copilot_options.outputs.copilot_ai }}
+          COPILOT_MODEL: ${{ vars.COPILOT_MODEL }}
         run: |
           PR_NUMBER=${{ github.event.pull_request.number }}
           VERSION=$(python3 .github/scripts/version_manager.py get 2>/dev/null | tail -n 1)
@@ -68,17 +88,20 @@ jobs:
           fi
           rm -f _full_diff_stat.txt
 
-          python3 .github/scripts/changelog_manager.py ai-summary \
+          SUMMARY_RESULT=$(python3 .github/scripts/changelog_manager.py ai-summary \
             --commits-file commits.txt \
             --version "$VERSION" \
             --output summary.md \
             --pr-title "$PR_TITLE" \
-            --diff-stat-file diff_stat.txt
+            --diff-stat-file diff_stat.txt | tail -n 1)
+          ENGINE=$(python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("engine") or "unknown")' "$SUMMARY_RESULT" 2>/dev/null || echo "unknown")
 
           {
-            echo "🤖 **AI Summary (project-auto-wizard)**"
+            echo "📋 **PR Summary (project-auto-wizard)**"
             echo ""
             cat summary.md
+            echo ""
+            echo "<sub>engine: ${ENGINE}</sub>"
           } > comment_body.md
 
           python3 -c 'import json; print(json.dumps({"body": open("comment_body.md", encoding="utf-8").read()}))' > comment_payload.json

package/payload/workflows/common/PROJECT-COMMON-AUTO-CHANGELOG-CONTROL.yaml

@@ -12,8 +12,8 @@
 #      commits) and bumps accordingly.
 #    - Otherwise: always patch+1 (legacy behavior).
 # 2. Generates the release summary locally with changelog_manager.py
-#    ai-summary (engine chain: user API key -> GitHub Models -> rule-based
-#    fallback; always succeeds, no third-party service involved)
+#    ai-summary (engine chain: user API key -> Copilot CLI, opt-in via
+#    version.yml copilot_ai -> rule-based fallback; always succeeds)
 #    - The AI prompt includes commit subjects plus a capped
 #      `git diff --stat` (file-level change summary, no diff body)
 #      for richer context without token-cost blowup.
@@ -34,8 +34,10 @@
 # - secrets.WORKFLOW_PAT: PAT used for the merge. Without it the merge is
 #   performed with GITHUB_TOKEN, and GitHub will NOT trigger downstream
 #   {{MAIN_BRANCH}}-push workflows (e.g. RELEASE-PUBLISH) for that merge.
-# - secrets.AI_API_KEY (+ vars.AI_API_BASE_URL / vars.AI_MODEL): preferred
-#   summary engine. Falls back to GitHub Models, then to rule-based.
+# - secrets.AI_API_KEY (+ vars.AI_API_BASE_URL / vars.AI_MODEL, all three
+#   required together): preferred summary engine. Falls back to Copilot CLI
+#   (only when version.yml copilot_ai is true; optional vars.COPILOT_MODEL),
+#   then to rule-based.
 #
 # Issue #90: without WORKFLOW_PAT, a wait-for-merge-and-trigger-release job
 # polls until the automerge actually lands, then wakes RELEASE-PUBLISH via
@@ -60,7 +62,7 @@ on:
 permissions:
   contents: write
   pull-requests: write
-  models: read
+  copilot-requests: write
 
 jobs:
   changelog-and-merge:
@@ -94,6 +96,20 @@ jobs:
           echo "semver_auto=$SEMVER_AUTO" >> $GITHUB_OUTPUT
           echo "semver_auto option: $SEMVER_AUTO"
 
+      - name: Read copilot_ai option from version.yml
+        id: copilot_options
+        run: |
+          # scoped to the metadata: -> template: -> options: chain so an
+          # unrelated "copilot_ai:" key can never hijack the value
+          COPILOT_AI=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?options:.*?copilot_ai:\s*\"?(true|false)", t, re.S); print(m.group(1) if m else "false")' 2>/dev/null || echo "false")
+          echo "copilot_ai=$COPILOT_AI" >> $GITHUB_OUTPUT
+          echo "copilot_ai option: $COPILOT_AI"
+
+      - name: Install Copilot CLI
+        if: steps.copilot_options.outputs.copilot_ai == 'true'
+        continue-on-error: true
+        run: npm install -g @github/copilot@1.0.88
+
       - name: Collect commits since last release
         id: collect
         run: |
@@ -149,6 +165,8 @@ jobs:
           AI_API_BASE_URL: ${{ vars.AI_API_BASE_URL }}
           AI_MODEL: ${{ vars.AI_MODEL }}
           GITHUB_TOKEN: ${{ github.token }}
+          COPILOT_AI: ${{ steps.copilot_options.outputs.copilot_ai }}
+          COPILOT_MODEL: ${{ vars.COPILOT_MODEL }}
         run: |
           # Idempotency: if the PR head is already this workflow's own
           # version-confirm commit (re-run / synchronize retrigger), do not
@@ -175,6 +193,7 @@ jobs:
           echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
 
       - name: Generate summary with the AI engine chain
+        id: summary
         env:
           # PR title goes through the env block — never inline-interpolate
           # untrusted text into the shell string (quote injection).
@@ -183,28 +202,37 @@ jobs:
           AI_API_BASE_URL: ${{ vars.AI_API_BASE_URL }}
           AI_MODEL: ${{ vars.AI_MODEL }}
           GITHUB_TOKEN: ${{ github.token }}
+          COPILOT_AI: ${{ steps.copilot_options.outputs.copilot_ai }}
+          COPILOT_MODEL: ${{ vars.COPILOT_MODEL }}
         run: |
           VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
 
-          python3 .github/scripts/changelog_manager.py ai-summary \
+          SUMMARY_RESULT=$(python3 .github/scripts/changelog_manager.py ai-summary \
             --commits-file commits.txt \
             --version "$VERSION" \
             --output summary.md \
             --pr-title "$PR_TITLE" \
-            --diff-stat-file diff_stat.txt
+            --diff-stat-file diff_stat.txt | tail -n 1)
+          ENGINE=$(python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("engine") or "unknown")' "$SUMMARY_RESULT" 2>/dev/null || echo "unknown")
+          echo "summary engine: $ENGINE"
+          echo "engine=$ENGINE" >> $GITHUB_OUTPUT
 
           # update-from-summary reads ./pr_body.md
           cp summary.md pr_body.md
 
       - name: Post AI summary comment
         continue-on-error: true
+        env:
+          ENGINE: ${{ steps.summary.outputs.engine }}
         run: |
           PR_NUMBER=${{ github.event.pull_request.number }}
 
           {
-            echo "🤖 **AI Summary (project-auto-wizard)**"
+            echo "📋 **PR Summary (project-auto-wizard)**"
             echo ""
             cat summary.md
+            echo ""
+            echo "<sub>engine: ${ENGINE:-unknown}</sub>"
           } > comment_body.md
 
           python3 -c 'import json; print(json.dumps({"body": open("comment_body.md", encoding="utf-8").read()}))' > comment_payload.json

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

@@ -59,7 +59,7 @@ on:
 
 permissions:
   contents: write
-  models: read
+  copilot-requests: write
 
 jobs:
   release:
@@ -160,6 +160,28 @@ jobs:
           echo "semver_auto=$SEMVER_AUTO" >> $GITHUB_OUTPUT
           echo "semver_auto option: $SEMVER_AUTO"
 
+      - name: Read copilot_ai option from version.yml
+        id: copilot_options
+        if: >-
+          steps.gate.outputs.proceed == 'true' &&
+          steps.mode.outputs.mode == 'trunk-based' &&
+          github.event_name == 'push'
+        run: |
+          # scoped to the metadata: -> template: -> options: chain so an
+          # unrelated "copilot_ai:" key can never hijack the value
+          COPILOT_AI=$(python3 -c 'import re; t=open("version.yml",encoding="utf-8").read(); m=re.search(r"metadata:.*?template:.*?options:.*?copilot_ai:\s*\"?(true|false)", t, re.S); print(m.group(1) if m else "false")' 2>/dev/null || echo "false")
+          echo "copilot_ai=$COPILOT_AI" >> $GITHUB_OUTPUT
+          echo "copilot_ai option: $COPILOT_AI"
+
+      - name: Install Copilot CLI
+        if: >-
+          steps.gate.outputs.proceed == 'true' &&
+          steps.mode.outputs.mode == 'trunk-based' &&
+          github.event_name == 'push' &&
+          steps.copilot_options.outputs.copilot_ai == 'true'
+        continue-on-error: true
+        run: npm install -g @github/copilot@1.0.88
+
       - name: Trunk-based version bump + changelog
         if: >-
           steps.gate.outputs.proceed == 'true' &&
@@ -170,6 +192,8 @@ jobs:
           AI_API_BASE_URL: ${{ vars.AI_API_BASE_URL }}
           AI_MODEL: ${{ vars.AI_MODEL }}
           GITHUB_TOKEN: ${{ github.token }}
+          COPILOT_AI: ${{ steps.copilot_options.outputs.copilot_ai }}
+          COPILOT_MODEL: ${{ vars.COPILOT_MODEL }}
         run: |
           # Idempotency: on a re-run of a failed job the checked-out HEAD may
           # already be this workflow's own docs commit — never bump twice.

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

@@ -26,8 +26,8 @@
 # ENV_FILE 또는 ENV: .env 파일 내용 (둘 중 하나, ENV_FILE 우선)
 # GOOGLE_SERVICES_JSON: Firebase google-services.json
 #
-# 🪄 빠른 설정: .github/util/flutter/firebase-wizard/firebase-wizard.html을
-#    브라우저에서 열어 5단계 마법사로 Firebase 배포를 자동 설정할 수 있습니다.
+# ※ 위 Secrets는 저장소 Settings → Secrets and variables → Actions에 등록하세요.
+#    FIREBASE_APP_ID·FIREBASE_TESTER_GROUP은 아래 env 섹션 값을 직접 수정합니다.
 #
 # ===================================================================
 #
@@ -53,6 +53,7 @@ name: PROJECT-FLUTTER-ANDROID-FIREBASE-APPDIST-CICD
 on:
   push:
     branches: ["{{MAIN_BRANCH}}"]
+    # @wizard paths-anchor (모노레포일 때 integrator가 paths 필터를 여기 주입)
   workflow_dispatch:
 
 env:
@@ -65,6 +66,10 @@ env:
   FLUTTER_VERSION: "3.35.5"
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
   PROJECT_TYPE: "flutter"
+  # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등 — 설치 시 자동 설정
+  FLUTTER_PROJECT_DIR: "."  # @wizard auto:flutter-root
+  # 환경변수 전달 방식 (dart-define | dotenv) — 설치 시 선택값으로 자동 설정
+  ENV_MODE: "dart-define"  # @wizard auto:flutter-env-mode
   # Firebase App Distribution 설정
   FIREBASE_APP_ID: "your-firebase-app-id"
   FIREBASE_TESTER_GROUP: "testers"
@@ -73,6 +78,9 @@ jobs:
   prepare-build:
     name: 환경 설정 및 준비
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ${{ env.FLUTTER_PROJECT_DIR }}
     # CHANGELOG 워크플로우가 성공한 경우에만 실행
     if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name != 'workflow_run' }}
 
@@ -91,12 +99,19 @@ jobs:
       - name: Pull latest changes
         run: git pull origin main
 
-      - name: Create .env file
+      - name: Prepare env file
         env:
           ENV_CONTENT: ${{ secrets.ENV_FILE || secrets.ENV }}
         run: |
-          printf '%s\n' "$ENV_CONTENT" > .env
-          echo ".env file created"
+          if [ "$ENV_MODE" = "dotenv" ]; then
+            printf '%s\n' "$ENV_CONTENT" > .env
+            echo ".env file created"
+          elif [ -n "$ENV_CONTENT" ]; then
+            DART_DEFINE_FILE="$RUNNER_TEMP/dart-define.env"
+            printf '%s\n' "$ENV_CONTENT" > "$DART_DEFINE_FILE"
+            echo "DART_DEFINE_FILE=$DART_DEFINE_FILE" >> "$GITHUB_ENV"
+            echo "dart-define file prepared"
+          fi
 
       - name: Set up Flutter
         uses: subosito/flutter-action@v2
@@ -108,7 +123,7 @@ jobs:
         uses: actions/cache@v6
         with:
           path: ~/.pub-cache
-          key: ${{ runner.os }}-flutter-pub-${{ hashFiles('**/pubspec.lock') }}
+          key: ${{ runner.os }}-flutter-pub-${{ hashFiles(format('{0}/**/pubspec.lock', env.FLUTTER_PROJECT_DIR)) }}
           restore-keys: ${{ runner.os }}-flutter-pub-
 
       - name: Install dependencies
@@ -121,6 +136,7 @@ jobs:
       # version_manager.py를 사용하여 현재 버전 정보 가져오기
       - name: 현재 버전 정보 가져오기
         id: current_version
+        working-directory: ${{ github.workspace }}   # version_manager.py가 레포 루트 version.yml을 읽어야 함
         run: |
           # VERSION 가져오기 (x.y.z 형식)
           VERSION=$(python3 .github/scripts/version_manager.py get | tail -n 1)
@@ -148,6 +164,7 @@ jobs:
       # CHANGELOG.json에서 릴리즈 노트 추출 - changelog_manager.py 사용
       - name: 릴리즈 노트 생성
         id: release_notes
+        working-directory: ${{ github.workspace }}   # CHANGELOG.json·changelog_manager.py·final_release_notes.txt(upload 짝)는 레포 루트 기준
         run: |
           VERSION="${{ steps.current_version.outputs.version }}"
 
@@ -192,15 +209,18 @@ jobs:
         with:
           name: project-files
           path: |
-            pubspec.yaml
-            lib/
-            assets/
+            ${{ env.FLUTTER_PROJECT_DIR }}/pubspec.yaml
+            ${{ env.FLUTTER_PROJECT_DIR }}/lib/
+            ${{ env.FLUTTER_PROJECT_DIR }}/assets/
           retention-days: 1
 
   build-android:
     name: Android AAB 빌드
     runs-on: ubuntu-latest
     needs: prepare-build
+    defaults:
+      run:
+        working-directory: ${{ env.FLUTTER_PROJECT_DIR }}
 
     steps:
       - name: Checkout repository
@@ -217,15 +237,22 @@ jobs:
         uses: actions/download-artifact@v8
         with:
           name: project-files
-          path: .
+          path: ${{ env.FLUTTER_PROJECT_DIR }}
 
-      # .env 파일 생성 (보안을 위해 아티팩트가 아닌 시크릿에서 생성)
-      - name: Create .env file
+      # 환경변수 준비 (보안을 위해 아티팩트가 아닌 시크릿에서 생성) — ENV_MODE=dotenv면 .env 파일, dart-define이면 임시 파일
+      - name: Prepare env file
         env:
           ENV_CONTENT: ${{ secrets.ENV_FILE || secrets.ENV }}
         run: |
-          printf '%s\n' "$ENV_CONTENT" > .env
-          echo "✅ .env 파일 생성됨 (크기: $(wc -c < .env) bytes)"
+          if [ "$ENV_MODE" = "dotenv" ]; then
+            printf '%s\n' "$ENV_CONTENT" > .env
+            echo ".env file created"
+          elif [ -n "$ENV_CONTENT" ]; then
+            DART_DEFINE_FILE="$RUNNER_TEMP/dart-define.env"
+            printf '%s\n' "$ENV_CONTENT" > "$DART_DEFINE_FILE"
+            echo "DART_DEFINE_FILE=$DART_DEFINE_FILE" >> "$GITHUB_ENV"
+            echo "dart-define file prepared"
+          fi
 
       # Release Keystore 설정
       - name: Setup Release Keystore
@@ -265,7 +292,7 @@ jobs:
         uses: actions/cache@v6
         with:
           path: ~/.pub-cache
-          key: ${{ runner.os }}-flutter-pub-${{ hashFiles('**/pubspec.lock') }}
+          key: ${{ runner.os }}-flutter-pub-${{ hashFiles(format('{0}/**/pubspec.lock', env.FLUTTER_PROJECT_DIR)) }}
           restore-keys: ${{ runner.os }}-flutter-pub-
 
       - name: Install dependencies
@@ -287,7 +314,7 @@ jobs:
           path: |
             ~/.gradle/caches
             ~/.gradle/wrapper
-          key: ${{ runner.os }}-gradle-${{ hashFiles('**/build.gradle*', '**/gradle-wrapper.properties') }}
+          key: ${{ runner.os }}-gradle-${{ hashFiles(format('{0}/android/**/build.gradle*', env.FLUTTER_PROJECT_DIR), format('{0}/android/**/gradle-wrapper.properties', env.FLUTTER_PROJECT_DIR)) }}
           restore-keys: |
             ${{ runner.os }}-gradle-
 
@@ -374,7 +401,8 @@ jobs:
             --release \
             --build-name="$VERSION_NAME" \
             --build-number="$VERSION_CODE" \
-            --verbose
+            --verbose \
+            ${DART_DEFINE_FILE:+--dart-define-from-file="$DART_DEFINE_FILE"}
 
           BUILD_EXIT_CODE=$?
 
@@ -524,7 +552,7 @@ jobs:
         uses: actions/upload-artifact@v7
         with:
           name: android-aab
-          path: build/app/outputs/bundle/release/app-release.aab
+          path: ${{ env.FLUTTER_PROJECT_DIR }}/build/app/outputs/bundle/release/app-release.aab
           retention-days: 1
 
   deploy-firebase:
@@ -544,7 +572,7 @@ jobs:
         uses: actions/download-artifact@v8
         with:
           name: android-aab
-          path: build/app/outputs/bundle/release/
+          path: ${{ env.FLUTTER_PROJECT_DIR }}/build/app/outputs/bundle/release/
 
       # 릴리즈 노트 다운로드
       - name: Download release notes
@@ -575,7 +603,7 @@ jobs:
           appId: ${{ env.FIREBASE_APP_ID }}
           serviceCredentialsFile: firebase-service-account.json
           groups: ${{ env.FIREBASE_TESTER_GROUP }}
-          file: build/app/outputs/bundle/release/app-release.aab
+          file: ${{ env.FLUTTER_PROJECT_DIR }}/build/app/outputs/bundle/release/app-release.aab
           releaseNotesFile: final_release_notes.txt
 
       # Firebase 인증 파일 삭제 (보안)