fix(ci): HF Space BUILD_ERROR 解消 + deploy 前後の検証多層化 by ayutaz · Pull Request #583 · ayutaz/piper-plus

ayutaz · 2026-06-28T17:40:50Z

Summary

HF Space (ayousanz/piper-plus-demo) が BUILD_ERROR で起動失敗していた症状を解消すると同時に、同種事故の再発を構造的に防ぐ多層防御 (deploy 前 2 gate + CI Layer 0/0.5/2.1/5 + post-deploy runtime verification) を追加する。既存 deploy ワークフローは upload_folder 成功で 0 exit するため、 HF Space が BUILD_ERROR / RUNTIME_ERROR / CONFIG_ERROR / NO_APP_FILE に陥っていても workflow が green になっていたのが今回の事象の根本理由。

Affected Components

Type

Risk Level

patch (内部の CI 補強 + 設定 sync。 runtime / artifact / public API には触れない)
minor
major

Contract Impact

None (spec TOML / public API / artifact format に変更なし)

変更内容

機能	動作	これがないと起こること
`huggingface-space/README.md` の `sdk_version: 6.9.0 → 6.16.0`	HF Space が gradio[oauth,mcp]==6.16.0 と requirements.txt の gradio==6.16.0 を矛盾なく resolve できる	既存事象の再現 (pip resolution conflict → BUILD_ERROR with misleading "cache miss" message)
`scripts/check_hf_space_gradio_sync.py` (sdk_version drift gate)	README frontmatter の sdk_version と requirements.txt の `gradio==X.Y.Z` exact pin の一致を検証	Dependabot が requirements.txt だけ bump して frontmatter を置き去りにする drift が検知されない
`scripts/check_hf_space_frontmatter.py` (F1-F4 対策)	README YAML frontmatter の schema gate。必須フィールド (title/sdk/sdk_version/app_file)、 app_file の実在、 sdk の妥当性、 YAML parse 可能性を検証	app_file typo / sdk typo / 必須フィールド削除 / YAML 構文破壊 → HF が CONFIG_ERROR / NO_APP_FILE / 汎用 BUILD_ERROR を返すが事前検知できない
`scripts/verify_hf_space_runtime.py` (F5、 universal safety net)	upload 後に `HfApi.get_space_runtime` を ~10min poll、 RUNNING/RUNNING_BUILDING/APP_STARTING のいずれかに到達するか BUILD_ERROR 等で fail するかを判定。 standalone 実行可能	upload は成功して workflow green、しかし HF Space は壊れたまま → 今回事象 (数週間誰も気付かない) が再発
`test-hf-space.yml`: Layer 0 (gradio sync) + Layer 0.5 (frontmatter)	PR 段階で 2 種類の frontmatter 整合性を強制	dev 直 push / GitHub web 編集による drift が CI を通過する
`test-hf-space.yml`: Layer 2.1 (`pip check`)	requirements インストール後の dependency conflict 検出	`pip install` は warning だけ出して exit 0 のことがあり、 HF 側の本番 resolve が ResolutionImpossible になっても気付かない
`test-hf-space.yml`: Layer 5 強化	`import app` だけでなく `create_interface()` まで実行し Gradio Blocks 構築を検証	gradio の API 破壊変更 (kwarg 名変更、 component 削除) が `import` 時には現れず、 HF Space launch 時に RUNTIME_ERROR となる
`deploy-huggingface.yml`: Set up Python + pre-deploy 2 gate (gradio sync / frontmatter)	upload 直前の最終防衛線	dev 直 push で drift が起きていても upload してしまう
`deploy-huggingface.yml`: post-deploy runtime verification (10 min poll)	upload 後に Space が RUNNING に到達するまで poll、失敗状態で fail	個別 gate が漏らした問題 (HF 側 build cache 汚染、 system library mismatch、 NLTK ダウンロード失敗等) が完全にすり抜ける
`.gitignore` 更新	新規 `check_hf_space_.py` / `verify_hf_space_.py` の allowlist 追加	scripts 配下の blanket ignore で新規 gate scripts が commit されない
`uv.lock` 再生成	PR #582 (Super-MAS) で pyproject.toml に追加された super-mas extra を反映	pre-commit が `uv sync` 時に lock drift を検知して fail

設計判断

post-deploy verification を universal safety net として最重要視: 個別 gate (frontmatter / pip check / Gradio build) は既知の failure mode しか塞げないが、 runtime 状態の poll は HF 側でしか発生しない未知の failure mode (system lib mismatch、 build cache 汚染、 yanked package、 NLTK サーバ down 等) もすべて捕まえる。今回事象が「workflow green = Space 動作 OK」という暗黙の前提を破壊したため、ここを明示検証する step を最優先で追加。
healthy stage に APP_STARTING / RUNNING_BUILDING を含めた: これらは RUNNING への遷移途中だが既に HTTP request を返している = 実質ユーザーから見て稼働中。タイムアウト時にこの状態でも green と判定することで「実際は動くのに workflow だけ red」を防ぐ。
timeout を 600s に設定: 通常 build 5-8 分 + HF queue 待ちで余裕。これより長いと「動いてはいるが build hang」として alert したい (workflow 全体の 30 min 上限内に収める)。
frontmatter gate で license: を検証しない: HF は accepted license リストを独自に更新するため、こちら側で hardcode 検証すると Dependabot 由来の license bump で false-positive する。 BUILD_ERROR 寄与度も低いため省略。
frontmatter gate と sdk_version sync gate を分離: 役割を明示することで「両方 fail」のときに原因切り分けが容易。 frontmatter gate は値同士の比較はしない。
uv.lock 修正を含めた理由: PR feat(train): Super-MAS Triton-GPU MAS accelerator (opt-in、推論影響ゼロ) #582 (Super-MAS) merge 時に pyproject.toml の super-mas extra が lock に反映されておらず、 pre-commit が uv sync を走らせると drift が顕在化する。本 PR は CI/CD 強化なので pre-commit 通過のため同梱が合理的。
bundle completeness check は後送り: 価値はあるが既存の import validation step である程度カバーされており、まず universal safety net を入れる方が ROI が高い。

Test Plan

python scripts/check_hf_space_gradio_sync.py (現行 README で OK + drift injection で fail)
python scripts/check_hf_space_frontmatter.py (現行 README で OK + 4 failure mode injection で全て exit 1)
python scripts/verify_hf_space_runtime.py --help (usage 表示)
unset HF_TOKEN; python scripts/verify_hf_space_runtime.py --space-id ayousanz/piper-plus-demo --timeout-seconds 5 (rc=2 で usage error)
PR CI の test-hf-space job で Layer 0 / 0.5 / 2.1 / 5 拡張すべて PASS
PR CI 全体が green
(post-merge) dev push 後の Deploy to Hugging Face Spaces workflow で post-deploy 検証 step が走り、 Space が RUNNING になることを実環境で確認

Checklist

Tests pass locally (両 gate の正常 + 失敗注入、 runtime script usage、 ruff lint/format pass)
No GPL/LGPL deps (PyYAML BSD-3, huggingface_hub Apache-2.0)
Documentation updated (script の docstring に設計判断・exit code 規約・運用ガイドを記述)

Related Issues

なし (HF Space BUILD_ERROR の調査・再発防止として自発提案、ユーザー指示「今後同じような問題が起きないように事前に hf のデプロイおよび動作保証を CI もしくはデプロイ前後で確認」に対応)。

HF Space (ayousanz/piper-plus-demo) が BUILD_ERROR で起動不能だった。 README frontmatter sdk_version=6.9.0 と requirements.txt gradio==6.16.0 が drift し、 HF Spaces ビルダーが pip install gradio==6.9.0 -r requirements.txt を 1 コマンドで実行するため resolution conflict で exit 1 (HF API は "cache miss" という misleading なメッセージで覆い隠していた)。修正: - huggingface-space/README.md: sdk_version を 6.16.0 に同期 (即時復旧) - scripts/check_hf_space_gradio_sync.py: 両者の exact pin 一致を検査する script を追加 (drift 時 exit 1 + 修正手順を提示) - .gitignore: 新 script を allowlist に追加 (check_*.py blanket ignore 対策) - .github/workflows/test-hf-space.yml: Layer 0 として gate を追加 (deps install 前に fail fast、 PR 段階で検出) - .github/workflows/deploy-huggingface.yml: upload_folder 直前にも同 gate を追加 (web UI 編集 / force-push の last-line defense) 根本原因は Dependabot #551 (2026-06-06) が requirements.txt のみ gradio 6.14.0 → 6.16.0 に bump し README frontmatter を同期しなかったこと。 gate により同種 drift を CI で事前検知可能。

github-actions · 2026-06-28T17:41:05Z

Required status-check gate (deferred)

Head SHA ff53707 is no longer the branch tip (latest: e845251). Waiting for the new commit's spoke runs to complete before re-evaluating.

github-actions · 2026-06-28T17:41:07Z

Action SHA drift report

Collected pins (3 actions) — expected_total_pins=3

Action	Pinned SHA	Resolved	Status
`dawidd6/action-download-artifact`	`8a33849`	(commit-only)	OK
`dawidd6/action-download-artifact`	`8a33849`	(commit-only)	OK
`mymindstorm/setup-emsdk`	`6ab9eb1`	(commit-only)	OK

Summary: total=3, ok=3

Copilot

Pull request overview

This PR fixes a Hugging Face Space build failure caused by Gradio version drift between the Space README frontmatter (sdk_version) and huggingface-space/requirements.txt, and adds a CI gate to prevent this drift from reoccurring.

Changes:

Sync huggingface-space/README.md sdk_version to match the pinned gradio==... in huggingface-space/requirements.txt.
Add scripts/check_hf_space_gradio_sync.py to validate README sdk_version ↔ requirements Gradio pin consistency.
Run the gate early in both the HF Space test workflow and the deploy workflow (pre-upload).

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/check_hf_space_gradio_sync.py	New validation script to enforce Gradio version consistency between README frontmatter and requirements pin.
huggingface-space/README.md	Bumps `sdk_version` to match the pinned Gradio version used by the Space.
.gitignore	Ensures the new `check_*.py` gate script is not ignored.
.github/workflows/test-hf-space.yml	Adds a fail-fast “Layer 0” step to detect version drift during PR validation.
.github/workflows/deploy-huggingface.yml	Adds a pre-deploy drift gate as last-line defense before uploading Space files.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

PR #583 初回 CI で pre-commit が 2 hook fail: 1. check-shebang-scripts-are-executable - scripts/check_hf_space_gradio_sync.py が shebang 付きで commit されたが git index の executable bit が 100644 のまま (Windows から add した時の既定動作) - 修正: git update-index --chmod=+x で 100755 に変更 2. artifact-retention-contract.toml gate (root cause: uv.lock drift) - 本 PR の .github/workflows/*.yml 変更が artifact-retention hook の file filter に match し hook が起動。 hook は uv run python ... で実行され、 uv が PR #582 (Super-MAS) で導入された [project.optional-dependencies] super-mas を uv.lock に未反映と検出して auto-sync (super-monotonic-align git dep + provides- extras に super-mas を追加) - hook 自体は "aligned with all upload steps" を出して contract toml に変更なし。 uv.lock の方が "files were modified by this hook" として fail 判定された - 修正: 同期された uv.lock を commit (#582 マージ後の latent drift を解消、本 PR の workflow 変更でたまたま surface した)

PR #583 で Copilot reviewer から指摘された 4 件 (すべて logic / correctness、 style noise ではない) を修正。 1. docstring と実装の exit code 不一致 (line 26) 旧: "exit 0 if both fields are absent" 実装: 片方 None でも errors.append → exit 1 → docstring を実装に揃え、空 pin も malformed として exit 1 を明記 2. 空 sdk_version 値を silently OK 化 (line 58) `sdk_version:` (値なし) で `""` を返し main の `is None` チェックを bypass → drift 検出を skip → `value or None` で空文字を None に正規化、統一的に malformed 扱い 3. 非 f-string で `{sdk_version}` がリテラル出力 (line 104) エラーメッセージの該当行に `f` prefix が抜けていた → f-string 化、実値を埋め込んで debug 性向上 (例: `gradio[oauth,mcp]==6.9.0`) 4. deploy-huggingface.yml gate が setup-python の前 (line 53) script が `str | None` 等 Python 3.10+ 構文を使うのに runner 既定 `python3` (バージョン非保証) に依存 → Set up Python を Setup deployment 直後に移動し、 gate を後に配置。後段の重複 setup-python step は削除、 `python3` を `python` に統一

PR #582 (Super-MAS Triton-GPU MAS accelerator) で pyproject.toml に追加された super-mas extra が uv.lock に未反映だった drift を解消。 PR #583 と同じ修正をこのブランチでも適用。

PR #583 の sdk_version drift 修正に続く防御層追加。既存検証では deploy upload 成功 = 0 exit で workflow が green になり、 HF Space が BUILD_ERROR / RUNTIME_ERROR / CONFIG_ERROR / NO_APP_FILE で起動失敗していても誰も気付かなかった (2026-06 incident の根本原因)。追加内容: 1. scripts/check_hf_space_frontmatter.py (F1-F4 対策) README YAML frontmatter の schema gate: - 必須フィールド (title / sdk / sdk_version / app_file) の存在 - app_file が huggingface-space/ 配下に実在 - sdk が gradio / streamlit / docker / static のいずれか - YAML が parse 可能 ruff + manual テスト (F1/F2/F3/F4 全 fail シナリオ + 正常 PASS) で動作確認。 2. scripts/verify_hf_space_runtime.py (F5 対策、 universal safety net) upload_folder 完了後、 HfApi.get_space_runtime を ~10 min poll し RUNNING / RUNNING_BUILDING / APP_STARTING のいずれかに到達するか BUILD_ERROR / RUNTIME_ERROR 等で fail するかを検出。タイムアウト時も fail (build hang を可視化)。 standalone 実行可能 (manual debug 用)。 3. test-hf-space.yml: Layer 0.5 (frontmatter) + Layer 2.1 (pip check) + Layer 5 を `import app` から `create_interface()` まで拡張 (gradio API breaking change を runtime 起動前に検知)。 4. deploy-huggingface.yml: Set up Python + pre-deploy frontmatter gate + post-deploy 10-min runtime verification。

Copilot AI review requested due to automatic review settings June 28, 2026 17:40

Copilot started reviewing on behalf of ayutaz June 28, 2026 17:41 View session

Copilot AI reviewed Jun 28, 2026

View reviewed changes

Comment thread scripts/check_hf_space_gradio_sync.py

Comment thread scripts/check_hf_space_gradio_sync.py Outdated

Comment thread scripts/check_hf_space_gradio_sync.py Outdated

Comment thread .github/workflows/deploy-huggingface.yml Outdated

ayutaz added 2 commits June 29, 2026 02:49

ayutaz mentioned this pull request Jun 28, 2026

feat(ci): HF Space deploy 前後の検証を追加 (BUILD_ERROR / RUNTIME_ERROR 即時検知) #584

Closed

28 tasks

ayutaz changed the title ~~fix(hf-space): gradio sdk_version drift を解消 + CI ゲート追加~~ fix(ci): HF Space BUILD_ERROR 解消 + deploy 前後の検証多層化 Jun 28, 2026

ayutaz merged commit 00c26c9 into dev Jun 28, 2026
79 checks passed

ayutaz deleted the fix/hf-space-gradio-sdk-version-sync branch June 28, 2026 23:14

ayutaz mentioned this pull request Jun 29, 2026

fix(pages): favicon SVG 同梱 + post-deploy 404 検知 gate を追加 #585

Merged

31 tasks

Navigation Menu

Uh oh!

fix(ci): HF Space BUILD_ERROR 解消 + deploy 前後の検証多層化 - #583

fix(ci): HF Space BUILD_ERROR 解消 + deploy 前後の検証多層化#583
ayutaz merged 4 commits into
devfrom
fix/hf-space-gradio-sdk-version-sync

ayutaz commented Jun 28, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 28, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ayutaz commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Affected Components

Type

Risk Level

Contract Impact

変更内容

設計判断

Test Plan

Checklist

Related Issues

Uh oh!

github-actions Bot commented Jun 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Required status-check gate (deferred)

Uh oh!

github-actions Bot commented Jun 28, 2026

Action SHA drift report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ayutaz commented Jun 28, 2026 •

edited

Loading

github-actions Bot commented Jun 28, 2026 •

edited

Loading