Static Web App 배포 회복 절차 (#1568)

docs-deploy.yml 의 Deploy to Azure Static Web Apps step 이 다음 오류로 반복 실패할 때:

The content server has rejected the request with: BadRequest.
Reason: No matching Static Web App environment was found.

본 가이드는 Build Docs 잡은 정상일 때 (즉 Docusaurus SSG 회귀가 아닐 때) 의 실 root cause 진단 + 회복 흐름입니다. SSG mermaid 회귀로 오인하지 마세요 — 본 회귀 가설은 audit (wh6c71j36, 2026-06-01) 에서 기각됨.

1. 진단 — 어디서 막혔는가

# 가장 최근 docs-deploy.yml 의 deploy step 결과
gh run list --workflow docs-deploy.yml --branch main --limit 10 \
  --json databaseId,conclusion,createdAt,headSha

# Build Docs 잡과 Deploy 잡 conclusion 분리 확인
gh run view <RUN_ID> --json jobs --jq '.jobs[] | {name, conclusion}'

패턴	의미
Build Docs success + Deploy failure	deploy 단계의 SWA env 매핑 문제 — 본 가이드 적용
Build Docs failure	Docusaurus SSG 회귀 — 본 가이드 무관, `docs-site` 코드 확인

2. 가능한 원인 + 회복

2-A. `AZURE_SWA_TOKEN` secret 회전됨

가장 흔한 원인. Azure portal 에서 SWA 토큰을 재발급한 후 GitHub secret 미반영.

# 1) Azure portal 에서 새 토큰 확보
az staticwebapp secrets list \
  --name gend-docs \
  --resource-group rg-gend-docs \
  --query "properties.apiKey" -o tsv

# 2) GitHub secret 갱신 (org-admin 또는 repo-admin 권한)
gh secret set AZURE_SWA_TOKEN --body "<NEW_TOKEN>" --repo genonai/DataX

# 3) 실패한 run 재실행
gh run rerun <RUN_ID> --repo genonai/DataX --failed

2-B. SWA portal 의 production environment 가 비활성화/삭제됨

environment.name: docs-production (workflow) ↔ Azure SWA portal 의 production env 이름이 불일치할 때.

# 현재 SWA 환경 목록
az staticwebapp environment list \
  --name gend-docs --resource-group rg-gend-docs -o table

default (= production, main branch) 가 보여야 함. 없으면 portal 에서 재바인딩 (Azure UI > Custom domains > production env 추가)
환경 이름이 'production' 외 다른 값이면 workflow yaml 의 deployment_environment 입력값을 그것에 맞춤

2-C. `production_branch` 입력값 누락 (defensive fix)

Azure/static-web-apps-deploy@v1 의 fallback 이 main 으로 가정하지만 명시하지 않으면 portal 설정 변경 시 끊김. #1568 에서 본 PR 이 production_branch: main + deployment_environment: production 명시 추가.

3. PR Preview 한도 초과 (별 원인)

This Static Web App already has the maximum number of staging environments — Free 플랜 3 staging 한도. 본 회귀 원인 아님:

gend-docs SWA 는 PR #1504 (2026-05-31) 로 PR Preview/cleanup 잡 자체가 제거됨 → 한도 초과 재발 불가
다른 SWA (quantai-docs 등) 에 PR Preview 신규 도입 시 cleanup-job 동반 필수 (운영자 메모리 feedback_swa_staging_cleanup.md — repo 외부)

4. 재발 방지 가드

운영자 점검 주기: 월 1회 az staticwebapp environment list 로 고아 env 0건 확인
GitHub secret 회전: AZURE_SWA_TOKEN 회전 시 본 워크플로우 1회 수동 실행으로 검증
회귀 가설 기각 marker: mermaid SSR / useColorMode 가설은 audit wh6c71j36 (2026-06-01) 에서 기각됨. 본 가이드를 우선 적용

1. 진단 — 어디서 막혔는가​

2. 가능한 원인 + 회복​

2-A. AZURE_SWA_TOKEN secret 회전됨​

2-B. SWA portal 의 production environment 가 비활성화/삭제됨​

2-C. production_branch 입력값 누락 (defensive fix)​

3. PR Preview 한도 초과 (별 원인)​

4. 재발 방지 가드​

관련​