project-auto-wizard 0.9.1 → 0.11.0

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 인증 파일 삭제 (보안)

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

@@ -16,6 +16,7 @@
 # RELEASE_KEY_PASSWORD: key 비밀번호
 # GOOGLE_SERVICES_JSON: Firebase google-services.json
 # GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64: Play Console 서비스 계정 (base64)
+# ANDROID_PACKAGE_NAME: 앱 패키지명 (Secret 우선, 없으면 Variable) — fastlane에 PACKAGE_NAME으로 전달
 # ===================================================================
 
 name: PROJECT-FLUTTER-ANDROID-PLAYSTORE-INTERNAL-CICD
@@ -23,6 +24,7 @@ name: PROJECT-FLUTTER-ANDROID-PLAYSTORE-INTERNAL-CICD
 on:
   push:
     branches: ["{{MAIN_BRANCH}}"]
+    # @wizard paths-anchor (모노레포일 때 integrator가 paths 필터를 여기 주입)
   workflow_dispatch:
     inputs:
       deploy_mode:
@@ -48,8 +50,10 @@ env:
   # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등.
   # 통합 시점에 integrator의 flutter-root resolver가 project_paths.flutter 값으로 1회 치환.
   FLUTTER_PROJECT_DIR: "."  # @wizard auto:flutter-root
-  # 배포 모드 (store_only | store_prepare | store_submit)
-  DEPLOY_MODE: ${{ github.event.inputs.deploy_mode || vars.ANDROID_DEPLOY_MODE || 'store_only' }}
+  # 환경변수 전달 방식 (dart-define | dotenv) — 설치 시 선택값으로 자동 설정
+  ENV_MODE: "dart-define"  # @wizard auto:flutter-env-mode
+  # 배포 모드 (store_only | store_prepare | store_submit) — 마지막 폴백값은 설치 시 선택값으로 설정, 변수·수동 입력이 항상 우선
+  DEPLOY_MODE: ${{ github.event.inputs.deploy_mode || vars.ANDROID_DEPLOY_MODE || 'store_only' }}  # @wizard fallback:android-deploy-mode
 
 jobs:
   prepare-build:
@@ -76,12 +80,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
@@ -93,7 +104,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
@@ -180,9 +191,9 @@ 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
           if-no-files-found: error
 
@@ -209,15 +220,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
@@ -257,7 +275,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
@@ -279,7 +297,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-
 
@@ -366,7 +384,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=$?
           
@@ -565,8 +584,13 @@ jobs:
       - name: Install Fastlane
         working-directory: ${{ env.FLUTTER_PROJECT_DIR }}/android
         run: |
-          # multi_json: google-apis transitive 의존성이 선언 누락한 upstream 버그 회피 (gemspec 미선언 → Gem::LoadError)
-          printf 'source "https://rubygems.org"\ngem "fastlane"\ngem "multi_json"\n' > Gemfile
+          # 저장소의 Gemfile에 fastlane이 있으면 그대로 쓴다 (Gemfile.lock 커밋 권장). 없으면 생성한다.
+          if [ -f Gemfile ] && grep -Eq "['\"]fastlane['\"]" Gemfile; then
+            echo "ℹ️ 저장소의 Gemfile을 사용합니다"
+          else
+            # multi_json: google-apis transitive 의존성이 선언 누락한 upstream 버그 회피 (gemspec 미선언 → Gem::LoadError)
+            printf 'source "https://rubygems.org"\ngem "fastlane"\ngem "multi_json"\n' > Gemfile
+          fi
           bundle install
           echo "✅ Fastlane 설치 완료 (Bundler)"
           bundle exec fastlane --version
@@ -585,6 +609,7 @@ jobs:
       - name: Upload to Play Store Internal Testing
         env:
           DEPLOY_MODE: ${{ env.DEPLOY_MODE }}
+          PACKAGE_NAME: ${{ secrets.ANDROID_PACKAGE_NAME || vars.ANDROID_PACKAGE_NAME }}
         run: |
           echo "=========================================="
           echo "🚀 Play Store 배포 시작"

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

@@ -25,6 +25,7 @@ name: PROJECT-Android-SelfHosted-CICD
 on:
   push:
     branches: ["{{MAIN_BRANCH}}"]
+    # @wizard paths-anchor (모노레포일 때 integrator가 paths 필터를 여기 주입)
   workflow_dispatch: # 수동 실행 옵션 추가
 
 # ============================================
@@ -35,6 +36,10 @@ env:
   APP_ARTIFACT_NAME: "__APP_ARTIFACT_NAME__"  # @wizard ask:@repo
   FLUTTER_VERSION: "3.35.5"
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
+  # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등 — 설치 시 자동 설정
+  FLUTTER_PROJECT_DIR: "."  # @wizard auto:flutter-root
+  # 환경변수 전달 방식 (dart-define | dotenv) — 설치 시 선택값으로 자동 설정
+  ENV_MODE: "dart-define"  # @wizard auto:flutter-env-mode
   # SMB 서버 설정 (자체 서버 — Synology NAS·Linux 등)
   SMB_PORT: "44445" # 기본 445
   SMB_SHARE: "web"
@@ -45,6 +50,9 @@ jobs:
     runs-on: ubuntu-latest
     # CHANGELOG 워크플로우가 성공한 경우에만 실행
     if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name != 'workflow_run' }}
+    defaults:
+      run:
+        working-directory: ${{ env.FLUTTER_PROJECT_DIR }}
 
     steps:
       # Repository 체크아웃 및 목록 출력
@@ -67,14 +75,20 @@ jobs:
           ls -la ~/.android/
           keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android || echo "Keytool failed"
 
-      # .env 파일 생성
-      - name: Create .env file from GitHub Secret
+      # 환경변수 준비 — ENV_MODE=dotenv면 .env 파일, dart-define이면 프로젝트 밖 임시 파일(--dart-define-from-file)
+      - name: Prepare env file
         env:
           ENV_CONTENT: ${{ secrets.ENV_FILE || secrets.ENV }}
         run: |
-          printf '%s\n' "$ENV_CONTENT" > .env
-          echo ".env file created"
-          ls -la
+          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
 
       # Keystore와 key.properties 설정
       - name: Setup Keystore and key.properties
@@ -117,7 +131,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: Cache Gradle dependencies
@@ -126,7 +140,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-
 
@@ -142,7 +156,7 @@ jobs:
 
       # Gradle 셋업
       - name: Setup Gradle
-        working-directory: android
+        working-directory: ${{ env.FLUTTER_PROJECT_DIR }}/android
         run: |
           chmod +x gradlew
           echo "Gradle wrapper permissions set"
@@ -159,27 +173,6 @@ jobs:
           echo "Java setup completed"
           java -version
 
-      # Ruby 설정 및 확인
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.4.1"
-
-      - name: Verify Ruby version
-        run: |
-          echo "Ruby setup completed"
-          ruby -v
-
-      # Fastlane 설치 (Bundler 방식 - gem 충돌 방지)
-      - name: Install Fastlane
-        working-directory: android
-        run: |
-          # multi_json: google-apis transitive 의존성이 선언 누락한 upstream 버그 회피 (gemspec 미선언 → Gem::LoadError)
-          printf 'source "https://rubygems.org"\ngem "fastlane"\ngem "multi_json"\n' > Gemfile
-          bundle install
-          echo "Fastlane installed (Bundler)"
-          bundle exec fastlane --version
-
       # 현재 버전 정보 및 짧은 커밋 해시 계산
       - name: Get version info and calculate short commit hash
         id: version_info
@@ -197,13 +190,12 @@ jobs:
           echo "현재 버전: $CURRENT_VERSION"
           echo "짧은 커밋 해시: $SHORT_COMMIT_HASH"
 
-      # Fastlane을 이용하여 APK 빌드 (릴리스 빌드 유지)
-      - name: Build APK with Fastlane
+      # APK 빌드 (릴리스 빌드 유지 — flutter로 직접 빌드)
+      - name: Build APK
         run: |
-          cd android
-          bundle exec fastlane build --verbose
-          ls -la ../build/app/outputs/flutter-apk/ || true
-          echo "APK built with Fastlane"
+          flutter build apk --release ${DART_DEFINE_FILE:+--dart-define-from-file="$DART_DEFINE_FILE"}
+          ls -la build/app/outputs/flutter-apk/ || true
+          echo "APK built"
 
       # APK 파일 이름 변경 및 준비
       - name: Rename and Prepare APK
@@ -218,7 +210,7 @@ jobs:
         uses: actions/upload-artifact@v7
         with:
           name: ${{ env.APP_ARTIFACT_NAME }}-apk
-          path: ./android/app/build/outputs/apk/release/${{ env.APP_ARTIFACT_NAME }}-v${{ env.VERSION }}-${{ env.SHORT_COMMIT_HASH }}.apk
+          path: ${{ env.FLUTTER_PROJECT_DIR }}/android/app/build/outputs/apk/release/${{ env.APP_ARTIFACT_NAME }}-v${{ env.VERSION }}-${{ env.SHORT_COMMIT_HASH }}.apk
           retention-days: 1
 
   deploy-android:

package/payload/workflows/flutter/PROJECT-FLUTTER-ANDROID-TEST-APK.yaml

@@ -39,8 +39,8 @@
 # 🔥 Firebase App Distribution (선택):
 # FIREBASE_SERVICE_ACCOUNT_JSON_BASE64: Firebase 서비스 계정 JSON (base64)
 #
-# 🪄 빠른 설정: .github/util/flutter/firebase-wizard/firebase-wizard.html을
-#    브라우저에서 열어 5단계 마법사로 Firebase 배포를 자동 설정할 수 있습니다.
+# ※ 위 Secrets는 저장소 Settings → Secrets and variables → Actions에 등록하세요.
+#    Firebase 업로드를 쓰려면 아래 env의 FIREBASE_APP_ID·FIREBASE_TESTER_GROUP도 수정합니다.
 #
 # ===================================================================
 
@@ -61,6 +61,11 @@ on:
 env:
   FLUTTER_VERSION: "3.35.5"
   JAVA_VERSION: "__JAVA_VERSION__"  # @wizard ask:17
+  # Flutter 루트 경로(레포 루트 기준). 단일레포면 ".", 모노레포면 "app" 등 — 설치 시 자동 설정
+  FLUTTER_PROJECT_DIR: "."  # @wizard auto:flutter-root
+  # 환경변수 전달 방식 (dart-define | dotenv) — 설치 시 선택값으로 자동 설정
+  ENV_MODE: "dart-define"  # @wizard auto:flutter-env-mode
+  # dotenv 모드에서 .env를 만들 경로 (Flutter 루트 기준)
   ENV_FILE_PATH: ".env"
   FIREBASE_APP_ID: "{FIREBASE_APP_ID}"
   FIREBASE_TESTER_GROUP: "{TESTER_GROUP}"
@@ -120,7 +125,7 @@ jobs:
                   '',
                   '### 💡 확인 사항',
                   '1. 브랜치가 원격 저장소에 push되었는지 확인하세요',
-                  '2. "Guide by SUH-LAB" 댓글의 브랜치명이 올바른지 확인하세요',
+                  '2. "Issue Helper" 댓글의 브랜치명이 올바른지 확인하세요',
                   '3. 브랜치명에 오타가 없는지 확인하세요',
                   '',
                   `🔗 [워크플로우 로그](${runUrl})`
@@ -299,6 +304,9 @@ jobs:
     name: Android 테스트 APK 빌드
     runs-on: ubuntu-latest
     needs: prepare-test-build
+    defaults:
+      run:
+        working-directory: ${{ env.FLUTTER_PROJECT_DIR }}
 
     steps:
       - name: Checkout repository
@@ -310,12 +318,20 @@ jobs:
       - name: Pull latest changes
         run: git pull origin ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch_name || github.ref_name }}
 
-      - name: Create .env file
+      # 환경변수 준비 — ENV_MODE=dotenv면 .env 파일, dart-define이면 프로젝트 밖 임시 파일(--dart-define-from-file)
+      - name: Prepare env file
         env:
           ENV_CONTENT: ${{ secrets.ENV_FILE || secrets.ENV }}
         run: |
-          printf '%s\n' "$ENV_CONTENT" > ${{ env.ENV_FILE_PATH }}
-          echo "✅ ${{ env.ENV_FILE_PATH }} file created"
+          if [ "$ENV_MODE" = "dotenv" ]; then
+            printf '%s\n' "$ENV_CONTENT" > "$ENV_FILE_PATH"
+            echo "✅ $ENV_FILE_PATH 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: Setup Release Keystore
         env:
@@ -371,7 +387,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: Cache Gradle dependencies
@@ -380,7 +396,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-
 
@@ -395,7 +411,7 @@ jobs:
 
       # Gradle 셋업
       - name: Setup Gradle
-        working-directory: android
+        working-directory: ${{ env.FLUTTER_PROJECT_DIR }}/android
         run: |
           chmod +x gradlew
           echo "✅ Gradle wrapper permissions set"
@@ -412,28 +428,6 @@ jobs:
           echo "✅ Java setup completed"
           java -version
 
-      # Ruby 설정
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: "3.4.1"
-          bundler-cache: true
-
-      - name: Verify Ruby version
-        run: |
-          echo "✅ Ruby setup completed"
-          ruby -v
-
-      # Fastlane 설치 (Bundler 방식 - gem 충돌 방지)
-      - name: Install Fastlane
-        working-directory: android
-        run: |
-          # multi_json: google-apis transitive 의존성이 선언 누락한 upstream 버그 회피 (gemspec 미선언 → Gem::LoadError)
-          printf 'source "https://rubygems.org"\ngem "fastlane"\ngem "multi_json"\n' > Gemfile
-          bundle install
-          echo "✅ Fastlane installed (Bundler)"
-          bundle exec fastlane --version
-
       # 진행상황 - 준비 완료
       - name: 진행상황 - 준비 완료
         id: progress_step1
@@ -539,18 +533,11 @@ jobs:
           echo "✅ pubspec.yaml 버전 변경 완료:"
           grep "^version:" pubspec.yaml
 
-      # APK 빌드 (Fastlane 또는 직접 빌드)
+      # APK 빌드 (flutter로 직접 빌드)
       - name: Build APK
         run: |
-          # Fastlane Fastfile이 있으면 사용, 없으면 직접 빌드
-          if [ -f "android/fastlane/Fastfile" ]; then
-            echo "📦 Fastlane을 사용하여 빌드..."
-            cd android
-            bundle exec fastlane build --verbose || flutter build apk --release
-          else
-            echo "📦 Flutter 직접 빌드..."
-            flutter build apk --release
-          fi
+          echo "📦 Flutter 직접 빌드..."
+          flutter build apk --release ${DART_DEFINE_FILE:+--dart-define-from-file="$DART_DEFINE_FILE"}
           ls -la ./build/app/outputs/flutter-apk/ || true
           echo "✅ APK built"
 
@@ -693,9 +680,9 @@ jobs:
         with:
           name: ${{ steps.apk_filename.outputs.artifact_name }}
           path: |
-            ./android/app/build/outputs/apk/release/*.apk
-            build-info.txt
-            build-metadata.json
+            ${{ env.FLUTTER_PROJECT_DIR }}/android/app/build/outputs/apk/release/*.apk
+            ${{ env.FLUTTER_PROJECT_DIR }}/build-info.txt
+            ${{ env.FLUTTER_PROJECT_DIR }}/build-metadata.json
           retention-days: 7
           if-no-files-found: error
 
@@ -730,9 +717,9 @@ jobs:
         uses: wzieba/Firebase-Distribution-Github-Action@v1
         with:
           appId: ${{ env.FIREBASE_APP_ID }}
-          serviceCredentialsFile: firebase-service-account.json
+          serviceCredentialsFile: ${{ env.FLUTTER_PROJECT_DIR }}/firebase-service-account.json
           groups: ${{ env.FIREBASE_TESTER_GROUP }}
-          file: ./android/app/build/outputs/apk/release/${{ steps.apk_filename.outputs.apk_name }}
+          file: ${{ env.FLUTTER_PROJECT_DIR }}/android/app/build/outputs/apk/release/${{ steps.apk_filename.outputs.apk_name }}
           releaseNotes: |
             테스트 빌드 #${{ needs.prepare-test-build.outputs.build_number }}
             브랜치: ${{ needs.prepare-test-build.outputs.branch_name }}