ひとり開発でChatGPT Codexを使うためのGitHub取扱説明書
ChatGPTのCodexを、「自分ひとりで使う」前提で、GitHubのどこをどう触ればいいかをまとめた取扱説明書です。
VS Code連携はなんとなく使えるけど、GitHub連携はよくわからない……という人向けに、
「触る場所」と「最低限の用語」に絞って解説します。
0. なにをしたいか（ゴール）
- ChatGPTのCodexに、自分のGitHubリポジトリを読ませる
- そのリポジトリの中で、Codexに
- コードを書かせる・直させる
- テストを実行させる
- Pull Request（プルリクエスト）を出させる
- 開発者は自分ひとりだけ（チーム開発ではない）
- GitHubの設定も、Codexと関係する部分だけに絞る
1. GitHubとCodexの関係をざっくり理解する
GitHubとは？
GitHub は、コード置き場 ＋ 変更履歴管理のサービスです。
プロジェクトごとに Repository（リポジトリ） という単位で管理します。
Codexとは？
Codex は、ChatGPTの中にいるコーディング専用エージェントのような存在です。
GitHubのリポジトリを読み込んで、
- コードの修正・リファクタリング
- 新機能の追加
- テストの追加・実行
- Pull Request（プルリクエスト）の作成
などを自動で行ってくれます。
「環境（Environment）」という考え方
Codexでは、基本的に
1つの GitHub リポジトリ ＝ 1つの Codex 環境（Environment）
という対応で管理します。
- Codexの管理画面で、GitHubリポジトリを指定して Create environment（環境を作成）
- その環境の中で、Codexがコードを読んで作業する
2. ひとり用で最低限覚えておけばいいGitHub用語
ひとりでCodex＋GitHubを使うだけなら、最初はこの4つをざっくり覚えておけばOKです。
Repository（リポジトリ）
プロジェクト単位のフォルダ。
ブラウザのURLが「https://github.com/ユーザー名/リポジトリ名」になっているページが、それにあたります。
Branch（ブランチ）
コードの「枝分かれ」＝別の状態の並行世界のようなもの。
通常は mainブランチ（main） が「本線」です。
Commit（コミット）
その瞬間のコードの スナップショット（保存ポイント）。
「どんな変更をしたか」を説明するメッセージ付きで保存されます。
Pull request（プルリクエスト / PR）
「このブランチの変更を main に取り込みたいです」という申請のようなもの。
Codexが自動でPRを作ってくれることもあります。
3. Codex用のGitHubリポジトリを作る手順
3-1. 新しいリポジトリを作成する
- GitHubにログインする
- 右上の＋（プラス）ボタンをクリック → New repository（新しいリポジトリ） を選択
- フォームに入力：
- Repository name（リポジトリ名）
例：my-codex-playground - Description（説明）：空でもOK
- Visibility（公開範囲）
- Public（公開）
- Private（非公開）
- Initialize this repository with:（初期化オプション）
- Add a README file（READMEを追加） に必ずチェックを入れるのがおすすめ
- Repository name（リポジトリ名）
- Create repository（リポジトリを作成） ボタンを押す
3-2. なぜ「Add a README file（READMEを追加）」が重要か？
ここをチェックせずに完全な「空リポジトリ」を作ると、後でCodex側がリポジトリを参照する際に
Provided git ref main does not exist
というエラーが出ることがあります。
これは、
- まだ1回もコミットがない
mainブランチが存在しない
といった状態でよく起こります。
最初から README を1ファイルだけでも置いておけば、main ブランチが自動で作られ、最初のコミットもできるので、このエラーを避けやすくなります。
覚え方：
「新しいリポジトリを作るときは、必ず『Add a README file』にチェック」と覚えておくと安心です。
4. ChatGPT / Codex と GitHub を接続する
4-1. ChatGPT側でGitHub連携を許可する
- ブラウザでChatGPTを開く
- 左サイドバーから Codex を開く
- Codexの画面内の案内に従って、Connect to GitHub（GitHubに接続） をクリック
- GitHubのポップアップが開くので、内容を確認して Authorize（認可する） をクリック
この操作により、GitHub側には「ChatGPT用のアプリ（OAuthアプリ）」がインストールされます。
確認したい場合は、
- GitHub右上の自分のアイコン → Settings（設定）
- 左メニューから Applications（アプリケーション）
- Authorized OAuth Apps（認可されたOAuthアプリ） に ChatGPT関連のアプリが表示されているはずです
このとき、GitHub側で
- All repositories（すべてのリポジトリ）
- Only select repositories（選択したリポジトリのみ）
のどちらを対象にするかを選べます。
ひとりで実験したいだけのときのおすすめ：
Only select repositories（選択したリポジトリのみ） を選んで、
Codexで使う実験用リポジトリだけにアクセス権を与えておくと安全です。
4-2. Codexの「環境（Environment）」を作る
- ChatGPTのCodex画面で、Settings（設定） もしくは Environments（環境） に相当するページを開く
- Create environment（環境を作成） をクリック
- フォームに必要事項を入力：
- GitHub organization（GitHub組織／アカウント）：自分のGitHubユーザー名
- Repository（リポジトリ）：作成したリポジトリ名
- Branch（ブランチ）：通常は
main
ここまで設定できれば、Codexがそのリポジトリのコードを読んで作業できる状態になります。
5. ひとり用の「最小構成」フロー
とりあえずCodexに何か作らせてみるまでの、最小限の流れを1本にまとめます。
- GitHubでリポジトリを作る
- New repository（新しいリポジトリ）
- Visibility（公開範囲）は Private（非公開）
- Add a README file（READMEを追加） にチェック
- Codexで「環境」を作る
- Connect to GitHub（GitHubに接続）
- Create environment（環境を作成）
- GitHub organization / Repository / Branch を指定
- Codexにタスクを指示する
- 例：「このリポジトリに、Pythonで○○するスクリプトを作って」など
- Codexが提案するファイルや変更内容を画面上で確認
- CodexからGitHubに反映させる
- Codexの画面から、変更内容を確認して問題なければ
- Push（プッシュ）
- Create PR（PRを作成）
- Codexの画面から、変更内容を確認して問題なければ
- GitHub側でPRをマージする
- リポジトリページ → Pull requests（プルリクエスト） タブ
- 該当PRをクリックして内容を確認
- 問題なければ Merge pull request（プルリクエストをマージ） ボタンで取り込む
6. GitHubで「よく触る画面」と主な項目
6-1. リポジトリのトップ画面
リポジトリを開くと、上部にいくつかタブが並んでいます。
- Code（コード）
ファイル一覧。基本的には常にここを見ます。 - Issues（イシュー）
バグやTODOのメモ置き場。ひとり開発なら、使っても使わなくてもOK。 - Pull requests（プルリクエスト）
変更提案（PR）の一覧。Codexが作ったPRもここに出ます。 - Actions（アクション）
GitHub Actions（自動テスト・自動ビルドなど）。
CodexとGitHub Actionsを連携させる場合に使いますが、最初は無理に触らなくてOKです。 - Settings（設定）
リポジトリ自体の細かい設定を行う画面です。
Codeタブの中でよく見る場所
- 左上の
main ▼と書かれている部分：
現在の Branch（ブランチ） を示します。 - 右側付近のボタン：
- Add file（ファイルを追加）
- Create new file（新しいファイルを作成）
- Upload files（ファイルをアップロード）
- <> Code（コード） ボタン
- Clone with HTTPS（HTTPSでクローン）
- Open with GitHub Desktop など
- Add file（ファイルを追加）
VS Codeからリポジトリをクローンするときは、Clone with HTTPS のURLを使うのが一般的です。
6-2. リポジトリの Settings（設定）で見る場所
General（全般）
- Repository name（リポジトリ名）：名前の変更
- Description（説明）：一言メモ
- Danger Zone（危険ゾーン）：
- Delete this repository（リポジトリを削除）
Branches（ブランチ）
- Default branch（デフォルトブランチ）
通常はmainになっています。
古いリポジトリなどで、ここがmasterのままになっている場合、 Codex側がmainブランチを探しにいって Provided git ref main does not exist エラーになることがあります。
古いリポジトリでトラブったときは：
Default branchをmainに変更する- もしくは、Codex環境の設定側で
Branchをmasterに合わせる
7. よくあるトラブルと対処法
Q1. 「Provided git ref main does not exist」と表示される
よくある原因：
- リポジトリにまだ1回もコミットがない（完全に空）
- デフォルトブランチが
mainではない（masterなど）
パターン1：完全に空リポジトリの場合
- GitHubでそのリポジトリを開く
- Add file → Create new file（ファイルを追加 → 新しいファイルを作成） から適当なファイルを作る、または README を作る
- Commit changes（変更をコミット） して、1回目のコミットを作る
- Codex側の環境を作り直す、または再読み込みする
パターン2：ブランチ名が違う場合
- リポジトリの Settings（設定） → Branches（ブランチ） を開く
- Default branch（デフォルトブランチ） が
masterなどになっていないか確認 - 可能なら
mainに変更するか、Codex側の設定でBranchをmasterに合わせる
Q2. CodexからGitHubのリポジトリが見えない
よくある原因：
GitHubに連携したとき、「アクセスしてよいリポジトリ」が絞られている場合があります。
確認方法：
- GitHub右上の自分のアイコン → Settings（設定）
- 左メニュー → Applications（アプリケーション）
- Authorized OAuth Apps（認可されたOAuthアプリ） の中からChatGPT関連のアプリを選択
- Repository access（リポジトリアクセス） の設定を確認
- All repositories（すべてのリポジトリ）
- Only select repositories（選択したリポジトリのみ）
Only select repositories になっている場合は、Codexで使いたいリポジトリがここに含まれているか確認し、必要なら追加します。
Q3. 「Gitそのものが全然わからない」けど大丈夫か？
ひとり × Codex前提なら、最初は次の操作だけ覚えておけば何とかなります。
- GitHubのWeb画面でやること
- New repository（新しいリポジトリ）
- Add a README file（READMEを追加）にチェック
- Settings → Branches で Default branch（デフォルトブランチ）を確認
- Codex側でやること
- Connect to GitHub（GitHubに接続）
- Create environment（環境を作成）
- 作業完了後、PRができたら GitHub の Pull requests（プルリクエスト）タブから Merge（マージ）する
ローカルで git push / git pull を直接叩く部分は、
VS Code の GUI（ソース管理機能）を少しずつ触りながら慣れていけばOKです。
8. ここから先、必要になったら触る拡張ネタ
この取扱説明書は、ひとまず 「CodexをGitHubリポジトリに繋いで動かすところまで」 をゴールに書いています。
興味が出てきたら、次のような内容を「別冊」として覚えていくと、さらに便利になります。
- GitHub Actions（Actionsタブ）：テストやビルドの自動化
- Codex CLI：ターミナルからCodexを使うコマンドライン版
- AGENTS.md：Codexに対する詳細な指示書をリポジトリ内に置いて、振る舞いをカスタマイズする方法
まずは本記事の内容だけで「リポジトリ作成 → Codex環境作成 → PRマージ」まで一通り動かし、
慣れてきたところで、必要な項目から少しずつ広げていくのがおすすめです。
