【Codex 】④　Codex Cloud実習：GitHub連携、Cloud環境作成、並列タスク、Pull Request統合まで

Codex CLI

前回の実習で完成させた「四則演算コマンドライン計算機」を題材に、ローカルのGitリポジトリをGitHubへ登録し、Codex Cloud環境を作成。Cocex appからCloud 環境で開発．

本稿は、途中で迷いやすかったGUI操作やトラブルも含めた備忘録。

要点は、以下の通り。

  • Local PC でCodex App を立ち上げ、Github Cloud上で開発．開発はBranchに対し行い、順次、Github本体にPR(Pull Request）＆Marge．アプリ完成後、GithubからLocal PCにPull.
  • Codex Appでは、Githubのブランチに対し、複数のタスクを並列実行（競合しない前提）できることを確認．
  • VSCode+Codexとの違い：順次差分を承認しながらLocalで開発するか、Github Cloudのブランチで開発し、最後にPull&Margeするかの違い

1. 今回の到達点

項目実績
題材Python四則演算CLI
GitHubリポジトリunikarei/codex-extension-tutorial（非公開）
ベースブランチmaster
Codex Cloud環境unikarei/codex-cloud-calculator
Cloud OS / ImageLinux / Ubuntu 24.04ベースのuniversal
Cloud PythonPython 3.12.13
依存関係Python標準ライブラリのみ
テスト21件 → 22件、すべて成功
並列タスクTASK-006（Cloud環境文書）とTASK-007（CLIテスト強化）
確認済みマージPR #1、PR #2、PR #3
統合記録TASK-008をCloud上で完了し、コミット95d4feeを作成

Windowsローカル→GitHub→Codex Cloud環境→並列Cloudタスク→Draft PR→Review / Merge→Windowsへ同期

2. 前提：ローカル側で完成していたもの

前回までに、以下の状態を作っていた。

  • app.py：加算、減算、乗算、除算、CLI引数処理、終了コード処理
  • test_app.py：計算ロジックとCLIのテスト21件
  • run.bat：Windowsからapp.pyを起動し、引数と終了コードを転送
  • docs/spec.md、docs/architecture.md、docs/task.md：Specification-Driven Development（SDD）文書
  • 基準コミット：63465c5 feat: complete four-operation calculator CLI

ローカル確認例：

python -B app.py 10 + 2
python -B app.py 10 "*" 2
python -B app.py 10 / 0
python -B -m unittest -v

3. GitHub CLIを導入し、ブラウザー認証する

3.1 GitHub CLIをインストール

winget install --id GitHub.cli --source winget

インストール直後にghが認識されない場合があった。新しいコマンドプロンプトを開くか、フルパスで実行する。

"C:\Program Files\GitHub CLI\gh.exe" --version

3.2 対話メニューを避けてブラウザー認証

矢印キーやEnterが効かないケースがあったため、認証方式をオプションで明示した。

"C:\Program Files\GitHub CLI\gh.exe" auth login ^
  --hostname github.com ^
  --git-protocol https ^
  --web ^
  --clipboard
GitHub CLIのブラウザー認証成功画面
図1　ブラウザーに「Congratulations, you’re all set!」と表示されれば認証成功。

確認：

"C:\Program Files\GitHub CLI\gh.exe" auth status
"C:\Program Files\GitHub CLI\gh.exe" auth setup-git

重要：コマンドプロンプトへ貼り付けるのはコマンド行だけにする。D:\...>、Windowsのバージョン表示、実行結果までまとめて貼ると、それらもコマンドとして解釈される。

3.3 ローカルリポジトリをGitHubへ登録

"C:\Program Files\GitHub CLI\gh.exe" repo create ^
  unikarei/codex-extension-tutorial ^
  --private ^
  --source=. ^
  --remote=origin ^
  --push

確認コマンド：

git remote -v
git status
"C:\Program Files\GitHub CLI\gh.exe" repo view --web

4. Codex AppをCloudモードへ切り替える

Codex Appはプロジェクトディレクトリから次のように起動した。

cd /d "D:\usr8_work\work_23_chatgpt\16_PoCs\1001_Codex\02_codex-extension-tutorial"
codex app .

新しいタスク画面の下部にある実行場所メニューで、「クラウド」を選択する。

Codex Appでクラウドモードを選ぶ画面
図2　「新しいWorktree」ではなく「クラウド」を選ぶ。

5. Codex Cloud環境を新規作成する

5.1 環境選択メニューから「新しく作成」

Codex Cloud環境を新規作成するメニュー
図3　既存環境の一覧の下にある「＋ 新しく作成」を押す。

この操作で内蔵ブラウザーが開く。最初はログイン画面が白紙になったが、内蔵ブラウザー右上のメニューからウェブ閲覧データを消去し、認証タブを閉じて環境作成を開き直すと解消した。

5.2 リポジトリと基本情報を設定

Codex Cloud環境の基本設定画面
図4　GitHubリポジトリ、環境名、説明、コンテナ画像を設定する。
設定値
GitHub組織unikarei
リポジトリcodex-extension-tutorial
環境名unikarei/codex-cloud-calculator
説明Python四則演算CLIのCodex Cloud実習環境
コンテナ画像universal

5.3 詳細設定

Codex Cloud環境の詳細設定と作成ボタン
図5　環境変数・シークレットは追加せず、キャッシュ有効、セットアップ自動、インターネットアクセス無効で作成した。

今回のプログラムは標準ライブラリだけで動くため、requirements.txtや追加インストールは不要である。最初の実習では高度な設定を増やさず、基本構成で開始した。

5.4 作成済み環境を使用する

作成されたCodex Cloud環境の詳細画面
図6　環境の詳細を確認し、「これを使用する」を押す。メールアドレスは公開用にマスクした。

6. 環境とブランチを選択してCloudタスクを開始

Codex Cloud環境を選択する画面
図7　タスク入力欄の環境メニューでunikarei/codex-cloud-calculatorを選択。
masterブランチを選択する画面
図8　ベースブランチはmasterを選択。

6.1 最初は読み取り専用調査

いきなりコードを変更せず、Cloud環境が正しくリポジトリを読めるか、テストが通るかを調査した。読み取り専用調査プロンプト

このリポジトリを読み取り専用で調査してください。
ファイルの変更、コミット、プッシュ、Pull Request作成は行わないでください。

次を報告してください。
1. 現在のブランチと最新コミット
2. app.pyの機能
3. test_app.pyのテスト件数と内容
4. AGENTS.mdとdocs配下に定義された開発ルール
5. python -B -m unittest -v の実行結果
6. Codex Cloud環境のPythonバージョン
7. 実行したコマンド
8. Cloud環境で不足している設定
9. 次に並列実行できる、互いに競合しない小規模な開発タスクを2件

調査結果は次のとおりだった。

  • Cloud側の作業ブランチ名はwork
  • 最新コミットは63465c5
  • Python 3.12.13
  • 21テストがすべて成功
  • CloudはLinuxのためcmd.exeがなく、run.batは実行できない
  • 右オペランド非数値入力の自動テストが不足

ポイント：タスクのベースにmasterを選んでも、Codex Cloudの内部作業ブランチはwork等になる。これは異常ではない。

7. SDDで並列タスクを先に定義する

並列作業を始める前に、docs/task.mdへTASK-006～TASK-008を追加した。

タスク内容変更対象
TASK-006Codex Cloud環境の検証手順を文書化docs/cloud-environment.md
TASK-007CLI回帰テストを強化test_app.py
TASK-008並列タスク統合後の最終検証docs/task.md

この計画変更をPR #1として作成し、masterへマージした。

SDD計画のPull Requestがマージされた画面
図9　PR #1「Add Codex Cloud parallel SDD task plan」をマージ。

8. 互いに競合しない2タスクを並列実行

並列実行で最も重要なのは、編集対象ファイルを分離することである。今回はTASK-006が文書ファイル、TASK-007がテストファイルだけを変更するように制約した。

並列化の設計：
TASK-006 → docs/cloud-environment.mdのみ
TASK-007 → test_app.pyのみ
両者ともdocs/task.mdは触らず、状態更新はTASK-008でまとめて行う。

Codex Cloudで2つのタスクが並列に動いている画面
図10　左側に2つのCloudタスクが同時に並び、個別の隔離環境で作業している。

8.1 TASK-006：Cloud環境文書

新規docs/cloud-environment.mdへ、環境名、リポジトリ、Python、依存関係、推奨検証コマンド、run.batを実行できない制約を記載した。

結果：

  • 変更：新規1ファイル、54行
  • Python 3.12.13
  • 既存21テスト成功
  • コミット：8ec4c26 docs: document Codex Cloud environment

8.2 TASK-007：CLIテスト強化

stdout.strip()による緩い比較をやめ、末尾改行を含む完全一致へ変更した。また、python -B app.py 10 + abcに相当する右オペランド非数値テストを追加した。

結果：

  • 変更：test_app.pyのみ
  • テスト：21件 → 22件
  • 22件すべて成功
  • コミット：f0442b5 test: strengthen CLI regression coverage

9. Cloud差分をレビューし、Draft PRをマージ

9.1 Codex Appで変更ファイルをレビュー

Codex AppでCloudタスクの変更差分をレビューする画面
図11　変更対象が指示どおり1ファイルだけかを確認する。ローカルへ持ってくる「Apply」ではなく、Cloud PRを作成する。

9.2 Draft PRのFiles changedを確認

GitHubのDraft Pull RequestでFiles changedを確認する画面
図12　Draft PR #2。Files changedが1件で、変更範囲がTASK-006だけであることを確認。

Draft Pull Requestは、そのままではマージできない。Ready for reviewへ変更してから、競合がないことを確認する。

Pull RequestをReady for reviewにしてマージする画面
図13　Ready for review後に「No conflicts with base branch」と「Merge pull request」を確認。

9.3 マージ実績

PRタイトル内容マージコミット
#1Add Codex Cloud parallel SDD task plandocs/task.mdへTASK-006～008を追加8d4473b
#2docs: document Codex Cloud environmentdocs/cloud-environment.mdを追加e62454e
#3test: strengthen CLI regression coveragetest_app.pyを強化、22テストe55774e
CLIテスト強化Pull Requestがマージされた画面
図14　PR #3が正常にマージされ、並列タスク2本の統合が完了。

10. TASK-008：統合後の最終検証

PR #2とPR #3をmasterへ統合後、TASK-008を実行した。変更対象はdocs/task.mdだけに限定し、TASK-006～008をdoneへ更新した。

Cloud上で確認した内容：

  • Python 3.12.13
  • python -B -m unittest -v：22件すべて成功
  • 10 + 2 → 12.0
  • 10 - 2 → 8.0
  • 10 * 2 → 20.0
  • 10 / 2 → 5.0
  • 10 / 0 → 標準エラー、終了コード2、Tracebackなし
  • 10 + abc → 標準エラー、終了コード2、Tracebackなし
  • docs/cloud-environment.mdが存在
  • git diff --check問題なし
  • app.pyとtest_app.pyにはTASK-008による追加変更なし

統合記録コミット：

95d4fee docs: complete Codex Cloud integration verification

執筆時点の注意：GitHub上で確認済みのマージはPR #1～#3である。TASK-008のコミットはCloud側で作成済みだが、最終PRの作成・マージ画面と、その後のWindows側git pull結果は本記録では未確認である。公開前に次節の手順を実施する。

11. Windowsローカルへ最終成果を同期する

最終PRをマージした後、Windowsの元リポジトリで実行する。

cd /d "D:\usr8_work\work_23_chatgpt\16_PoCs\1001_Codex\02_codex-extension-tutorial"

git pull --ff-only origin master

python -B -m unittest -v

cmd /c run.bat 10 + 2
cmd /c run.bat 10 "*" 2
cmd /c run.bat 10 / 0
echo %ERRORLEVEL%

git log --oneline --decorate -7
git status

期待結果：

Ran 22 tests
OK

12.0
20.0
error: b must not be zero
2

CloudはLinux互換コードとPythonテストを担当し、Windows固有のrun.batはローカルPCで確認する。この役割分担を明文化したことも今回の成果である。

12. 途中で発生した問題と対策

問題原因対策
ghが認識されないwingetインストール後、既存CMDへPATHが反映されていないCMDを開き直す。急ぐ場合は"C:\Program Files\GitHub CLI\gh.exe"を使用
GitHub CLIの選択画面で矢印・Enterが効かない対話UIと端末の相性auth login --hostname ... --web --clipboardで選択を省略
CMDで大量の「コマンドではありません」プロンプトや実行結果まで一括貼り付けコードブロック内のコマンドだけを1行ずつ貼る
Codex内蔵ブラウザーの認証画面が白紙内蔵ブラウザーのCookie・キャッシュ不整合右上メニュー → ウェブ閲覧データを消去 → タブを閉じて再度開く
リポジトリ名を検索しても見つからない検索欄がリポジトリではなく「作成済み環境」の検索だった「＋ 新しく作成」から環境作成画面へ進む
Cloud上の現在ブランチがworkCodex Cloudがタスク用作業ブランチを自動作成ベースがmasterなら正常
run.batをCloudで実行できないCloudはLinuxでcmd.exeがないPython部分はCloud、バッチはWindowsローカルで検証
乗算の*がシェル展開されるワイルドカード解釈"*"のように引用する
Draft PRをマージできないDraftは作業中扱いReady for reviewへ変更後にマージ
並列PRが競合しそう複数タスクが同じファイルを変更タスクごとに変更許可ファイルを明示し、共通文書の更新は統合タスクへ集約

13. 今回わかったCodex Cloudの使いどころ

13.1 ローカルCodex Appとの違い

  • ローカル作業：Windows上のファイル、run.bat、Worktreeを直接扱いやすい
  • Cloud作業：GitHubを基準に、隔離されたLinux環境で複数タスクを並行実行できる
  • 成果物の受け渡し：CloudではPRを通じてレビューし、masterへ統合する

13.2 小さなPRに分ける効果

今回のPR #2は文書だけ、PR #3はテストだけだった。GitHubのFiles changedで変更意図を短時間に確認でき、競合も起きなかった。大きな変更を1本にまとめるより、目的と変更範囲を限定したPRの方がレビューしやすい。

13.3 SDDとCloud並列実行は相性がよい

先にdocs/task.mdへ変更対象と受け入れ条件を記録すると、各Cloudタスクへ「変更してよいファイル」「変更してはいけないファイル」を明示できる。並列実行時の暴走や競合を減らすうえで有効だった。

14. まとめ

今回の実習では、単にCodex Cloudでコードを生成するのではなく、次の一連の開発フローを体験できた。

  1. ローカルGitリポジトリをGitHubへ登録
  2. Codex Cloud環境を作成
  3. 読み取り専用調査で環境とテストを確認
  4. SDD文書へ並列タスクを登録
  5. 変更ファイルが重ならない2タスクを同時実行
  6. Codex Appで差分レビュー
  7. Draft PR → Ready for review → Merge
  8. 統合後に22テストを再実行
  9. Windows固有処理はローカルで最終確認

最大の学び：Codex Cloudの価値は、単発のコード生成よりも「GitHubを基準に、複数の小さなタスクを隔離して実行し、PRで人間が確認して統合する」開発プロセスにある。

15. 参考資料

コメント

タイトルとURLをコピーしました