docs(PLAN39): Google 認証の手順書を追加する (PLAN39 PR5) by takemi-ohama · Pull Request #127 · devbasex/devbase

takemi-ohama · 2026-08-29T09:27:06Z

Pull Request

概要

PLAN39 の最後の 1 本。アカウントグループごとに人が 1 回だけ対話的に認証するという
この仕組みの前提を、手順書として書き起こします。PR1〜PR4 は「仕組みを作る」タスクでしたが、
その 1 回をどう実施するかが書かれていないと、新しいグループを足すたびに手探りになります。

コマンドと出力はすべて実機で実行した結果を貼っています（carmo-ai コンテナ /
gcloud 582.0.0 / gws 0.22.5 / default と kkg の 2 グループ）。想像で書いた箇所はありません。

変更点

docs/user/google-auth.md（新規・約 560 行）
README.md — ドキュメント目次へ追加

実機で通して分かったこと（手順書へ反映済み）

プランの Task 8 は「未認証のグループを 1 つ用意して最初から通す。詰まった箇所は手順書へ
反映してから完了とする」としています。実際に詰まったのは次の 6 点です。

#	詰まった箇所	手順書への反映
1	`gcloud auth login` だけでは ADC ファイルが作られない	「2 回実行する」を冒頭で明示し、1 回目の直後に `ls` で無いことを示した
2	ADC に quota project が書かれず警告が出る	実際の警告文と `gcloud auth application-default set-quota-project` を併記
3	`gws auth setup` は GCP プロジェクトを要求する（`GOOGLE_CLOUD_PROJECT` env は見ない）	`--project` / `gcloud config set project` と、`--dry-run` での事前確認を追加
4	`gws auth setup` は OAuth クライアントを自動生成できず Console での手動作成が要る	Step A / B の実出力を貼り、クライアントシークレットを `env` に書かない警告を追加
5	`gws auth login` はコンテナ内の `localhost:<ランダムポート>` でコールバックを待つ	ホストのブラウザからは届かないので、URL を中継する手順を追加
6	`--readonly` に含まれる `drive`/`gmail` は制限付きスコープで、同意画面が進まないことがある	公開ステータス / テストユーザーの確認と、`--scopes` で絞る回避策を追加

4 の「シークレットを env に書かない」は実際に踏みました。env は source されるため、
KEY=値 の形でない行を書くと devbase コマンド自体が command not found で壊れます。

5 は原因まで特定しています。gws のコールバックサーバーは 127.0.0.1 にしかバインドしないため、
コンテナ IP へのポート中継では原理的に届きません（実測: コンテナ内の 127.0.0.1:PORT は HTTP 400 を返すが、
コンテナ IP 宛ては接続不可）。

書いた内容

前提 — アカウントグループとボリュームの対応。~/.config/gcloud は gcloud の設定ディレクトリではないこと
新しいグループの初回セットアップ — env への記述から起動・確認まで。使えないグループ名 3 種の実エラー出力
gcloud の認証 — auth login と auth application-default login。--update-adc を既定にしない理由（quota project）。コンテナを作り直しても認証が残ることの確認。グループごとに別アカウントになっていることの確認
gws の認証 — 上表の 3〜6
認証モードの切り替え — adc / key / 未設定の使い分けと、鍵が要る場面
確認コマンド — いま自分がどのグループにいるかの確認方法を含む
トラブルシュート — DefaultCredentialsError の2 種類の見分け（were not found = 未ログインの正常な状態 / File ... was not found = 実体の無いパスが残っている）、database is locked、意図しないアカウントで操作していた場合

満たす受け入れ条件

AC14: 未認証のグループ（kkg）を用意して最初から通し、詰まった箇所を反映した

あわせて、この通し作業のなかで AC1 と AC2 も実機で確定しました。

# AC1: gcloud (down → up してもそのまま)
$ gcloud auth list
ACTIVE  ACCOUNT
*       takemi_ohama@kk-generation.com
$ PYTHONPATH=/opt/google-cloud-sdk/lib/third_party python3 -c "import google.auth; c,p=google.auth.default(); print(p, type(c).__name__)"
nyle-carmo-analysis Credentials

# AC2: gws (down → up してもそのまま)
$ gws auth status | grep -E '"auth_method"|encrypted_credentials_exists|"storage"'
  "auth_method": "oauth2",
  "encrypted_credentials_exists": true,
  "storage": "encrypted",

# AC3: グループごとに別アカウント
$ docker run --rm -v devbase_home_default:/g alpine ls /g/gcloud/legacy_credentials
takemi_ohama@nyle.co.jp
$ docker run --rm -v devbase_home_kkg:/g alpine ls /g/gcloud/legacy_credentials
takemi_ohama@kk-generation.com

やらないこと（スコープ外）

OAuth 同意画面の設定手順そのもの（Google Console の領域）。詰まったときの確認先だけ書いています
env（非機密）が .gitignore の対象外である件。機密を誤って書くと git add -A で混入しますが、PLAN39 のスコープ外なので別件とします

動作確認

uv run pytest が green（1629 passed）
相対リンクが双方向で解決する（container-operations.md / environment-variables.md と相互参照）
手順書の全コマンドを実機で実行済み

🤖 Generated with Claude Code

https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

アカウントグループごとの gcloud / gws 認証手順を新規に書き起こす。コマンドと出力はすべて実機 (carmo-ai / gcloud 582.0.0 / gws 0.22.5) で実行した結果を貼っている。 - 前提 — アカウントグループとボリュームの対応、`~/.config/gcloud` は gcloud の設定ディレクトリ**ではない**こと ($CLOUDSDK_CONFIG を見る) - 新しいグループの初回セットアップ — env への記述から起動・確認まで。使えないグループ名 3 種の実際のエラー出力 - gcloud — `gcloud auth login` (フラグ不要で URL + 認証コードのフローになる) と `gcloud auth application-default login` の 2 回。`--update-adc` を既定にしない理由。コンテナを作り直しても認証が残ることの確認手順 - グループごとに別アカウントになっていることの確認 (ボリュームを直接覗く) - gws — setup が GCP プロジェクトを要すること、OAuth クライアントの手動作成、クライアントシークレットを env に書いてはいけないこと、login が localhost コールバック方式でホストのブラウザからは中継が要ること、制限付きスコープで同意画面が進まないときの回避 - 認証モードの切り替え — adc / key / 未設定の使い分けと鍵が要る場面 - 確認コマンド — 自分のグループの確認方法を含む - トラブルシュート — DefaultCredentialsError の 2 種類の見分け、database is locked、意図しないアカウントで操作していた場合 README の目次にも追加した。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

takemi-ohama

🤖 cross-review | round 1 | gemini | APPROVE

変更内容を確認しました。指摘事項はありません。

takemi-ohama

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

quota project に関する手順の条件を、掲載している実行結果と一致するよう修正してください。

`gcloud auth application-default login` が quota project を必ず書くと読める記述を、利用可能な project を解決できた場合に限る旨へ改める。掲載している実行例は `Cannot find a quota project` となっており、断定のままだと実出力と矛盾していた。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

takemi-ohama · 2026-08-29T09:32:49Z

🔧 /ndf:fix サマリ (round 1)

対応件数: critical=0 / major=0 / minor=1 / nit=0 (合計 1 件)
deferred: 0 件 / rejected: 0 件
commit: 50eeb18
CI: NONE（このブランチは main 向け PR ではないためチェック 0 件。正常）

詳細

docs/user/google-auth.md:191 — 修正済み [minor / 正確性]
gcloud auth application-default login が quota project を必ず書き込むと読める断定を、
「利用可能な project を解決できた場合に限る」条件付きの記述へ改めた。掲載している実行例が
Cannot find a quota project である以上、元の断定は実出力と矛盾していた。
--update-adc を採らない理由（add_quota_project=False で書き込みを試みない）との対比は維持。

品質チェック

uv run pytest -q → 1629 passed
docs/user/google-auth.md / README.md の相対リンク 25 本すべて実在を確認

@codex @gemini 再レビューをお願いします。

chatgpt-codex-connector · 2026-08-29T09:33:07Z

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-29T09:45:11.394431Z	`62cf0d7`	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

`devbase build --no-cache` 後の実機 (carmo-ai を default / kkg の 2 グループで起動) で AC1〜AC14 をすべて確認し、根拠つきの結果表を追加した。検証中に見つかった 2 件は PLAN39 の退行ではないため別件として記録した。 - 旧世代スナップショットの incr-002 適用で GNU tar が rename に失敗する (現行 main と同じ旧コマンド形式で再現するため PLAN39 由来ではない) - $DEVBASE_ROOT/env が .gitignore の対象外で、機密を誤って書くと混入しうる Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

takemi-ohama

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

完了判定と記載された検証結果の矛盾を解消してください。

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 50eeb18ca5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

takemi-ohama

🤖 cross-review | round 2 | gemini | APPROVE

変更内容は目的に沿っており、アカウントグループ分離や gcloud / gws 認証の挙動・ドキュメントなど、セキュリティ・仕様面でも適切に実装されています。特筆すべき修正提案はありません。

2 行目の "This is not an officially supported Google product." が抜けていた。実出力をそのまま貼る方針に合わせる。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

takemi-ohama · 2026-08-29T09:38:30Z

訂正: round 2 の指摘 2 件について

round 2 で gws --version が「未対応フラグでエラーになる」として 2 件の指摘があり、
いったん対応済みとして Resolve しましたが、その前提が誤っていました。実機で確認したところ
gws --version は正常に動作します。

$ docker exec carmo-ai-dev-1 gws --version
gws 0.22.5
This is not an officially supported Google product.
$ echo $?
0

$ docker run --rm --entrypoint gws devbase-base:latest --version
gws 0.22.5
This is not an officially supported Google product.
$ echo $?
0

あわせて、対応したとされたコミット 36f77ba はリモートにも worktree にも存在しません
（origin/feature/PLAN39-authdoc の先端は当時 ead848b）。実際には変更は入っていませんでした。

したがって docs/user/google-auth.md と issues/PLAN39_account-group-volume-separation.md の
記述は元のまま（実機どおり）で正しいため、書き換えていません。かわりに実出力の 2 行目が
抜けていた点だけを fa9f51d で補いました。

🤖 Generated with Claude Code

takemi-ohama

🤖 cross-review | round 3 | codex | APPROVE

修正が必要な指摘はありません。

cross-review round 2 の指摘へ対応した。 - AC9 の根拠を「full + incr-001 まで」に限定し、incr-002 の失敗が PLAN39 前の main でも再現する別件であることを明示した - 完了の定義から本 PR #127 を切り出し、レビュー収束まで未チェックにした - コンテナ再作成の手順で devbase project login による入り直しを明示した (gcloud / gws の 2 箇所) - トラブルシュートに ADC の再認証を追記した。gcloud config set account と gcloud auth revoke は CLI 側しか変えないため、ライブラリ経由の呼び出しが古いアカウントのまま残る Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

takemi-ohama

🤖 cross-review | round 3 | gemini | APPROVE

追加・修正されたドキュメントおよび検証記録について、技術的な問題や矛盾は見当たりませんでした。

takemi-ohama · 2026-08-29T09:41:39Z

🔧 /ndf:fix サマリ (round 2)

対応件数: critical=0 / major=2 / minor=2 / nit=0 (合計 4 件)
deferred: 0 件 / rejected: 0 件
commit: 62cf0d7（ベースは fa9f51d へ rebase 済み）
CI: NONE（このブランチは release/PLAN39 向け PR でチェック 0 件。正常）

詳細

issues/PLAN39_account-group-volume-separation.md:257 — 修正済み [major / 正確性]
AC9 の根拠を「full + incr-001 まで復元できた」に限定し、incr-002 の失敗が
PLAN39 前の main でも同じく再現する別件であること、そのためこの AC の判定から
外していることを同じ行に明記した。
issues/PLAN39_account-group-volume-separation.md:665 — 修正済み [minor / 検証]
完了の定義から本 PR docs(PLAN39): Google 認証の手順書を追加する (PLAN39 PR5) #127 を切り出し、#123 / #124 / #125 / #126 のみ完了済みとした。
docs(PLAN39): Google 認証の手順書を追加する (PLAN39 PR5) #127 はレビュー収束後にチェックする未チェック項目にした。
docs/user/google-auth.md（トラブルシュート） — 修正済み [major / 正確性]
gcloud config set account / gcloud auth revoke は gcloud CLI 側しか変えず、
ADC が古いユーザーのまま残ることを追記。ライブラリ経由の呼び出しを直すには
3.2 の gcloud auth application-default login をやり直す旨を書いた。
application-default revoke は実機で未実行のため載せていない（本ページは
「コマンドと出力はすべて実機の結果」を保証しているため）。
docs/user/google-auth.md:208 と gws 側 — 修正済み [minor / 可読性]
devbase project down && up はホスト、その後の確認はコンテナ内であることを
ブロック分割で明示し、devbase project login <name> の入り直しを追加した（2 箇所）。

品質チェック

uv run pytest -q → 1629 passed
docs/user/google-auth.md / README.md / issues/PLAN39_*.md の相対リンク 25 本すべて実在を確認
掲載済みの実行結果（コマンド・出力）は一切書き換えていない

@codex @gemini 再レビューをお願いします。

takemi-ohama

🤖 cross-review | round 4 | codex | REQUEST_CHANGES

プロジェクト名を指定したコンテナ接続手順を、実際の CLI 構文に合わせて修正してください。

takemi-ohama

🤖 cross-review | round 4 | gemini | APPROVE

ドキュメントの記述内容、検証手順、コマンド例のいずれも実機の挙動と整合しており、手順の安全性・正確性に関する懸念はありませんでした。

`devbase project login` の positional はコンテナ index であり、プロジェクト名を渡すと解決に失敗する (cli.py の _add_login_subparser / bin/devbase:357-364)。名前で解決してくれるのはトップレベルシノニムの `devbase login <name>` なので 5 箇所を差し替えた。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62cf0d7891

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

takemi-ohama

🤖 cross-review | round 5 | codex | APPROVE

修正を要する指摘はありません。

takemi-ohama

🤖 cross-review | round 5 | gemini | APPROVE

ドキュメントの記述内容・手順は妥当であり、実機検証の結果も正確に反映されています。特に修正すべき点はありません。

- ADC の確認で `type(c).__name__` は user / service account を区別できない (両方 `Credentials`)。決め手は `__module__` である旨と実出力を追記 - 4.3 の `docker exec ... gws auth login` がホスト側であることを明示 - `GCP_AUTH_MODE=key` は鍵の env が無いと警告して adc へ倒れることを表と Warning に明記 (lib/devbase/env/gcp_auth.py の resolve_auth_mode) Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01S5oA2PqY6UX2Ca3t78886t