Coding の GitHub アクセスを設定する

GitHub App を登録してインストールし、Client ID を設定して HTTPS Git と Pull Request を利用します

このガイドでは、リポジトリ単位の GitHub App を使って Coding を GitHub に接続します。設定後、Minara は認証した GitHub アカウントで HTTPS Git 操作と Pull Request 作成を行えます。

GitHub remote を確認する

リポジトリが GitHub を参照していることを確認します。

git remote -v

[email protected]:owner/repo.git と https://github.com/owner/repo.git のどちらも利用できます。Minara は承認した GitHub アカウントを使い、認証が必要な通信を HTTPS で行います。checkout に設定された remote は変更しません。

前提条件

個人アカウントまたは Organization で GitHub App を作成できること。
対象リポジトリに App をインストールできること。Organization Owner の承認が必要な場合があります。
開発ビルドを設定する場合は Minara Agent のソース checkout があること。

1. GitHub App を登録する

GitHub の Settings を開きます。
Developer settings を選択します。
GitHub Apps を選択します。
New GitHub App を選択します。
対象リポジトリを所有するアカウントを選びます。Organization のリポジトリでは、可能なら同じ Organization で App を作成します。

登録フォームを次のように設定します。

設定	値
GitHub App name	`Minara Coding` などの一意な名前
Homepage URL	製品、Organization、またはリポジトリの URL
Callback URL	空欄。Device Flow では使用しません
Expire user authorization tokens	有効のままにする
Request user authorization during installation	無効のままにする
Enable Device Flow	有効
Webhook Active	無効
Where can this GitHub App be installed?	所有者が 1 つなら `Only on this account`、複数なら `Any account`

Minara Desktop はローカルで認証を開始し、ブラウザで確認するため Device Flow を使います。

2. リポジトリ権限を設定する

Repository permissions では次の権限だけを設定します。

権限	アクセス	用途
Contents	Read and write	HTTPS 経由の Git オブジェクトの fetch と push
Pull requests	Read and write	Pull Request の検索と作成
Metadata	Read-only	リポジトリ ID とメタデータの読み取り

その他のリポジトリ、Organization、アカウント権限は No access のままにします。完了したら Create GitHub App を選択します。

3. App をリポジトリにインストールする

作成した GitHub App の設定ページを開きます。
Install App を選択します。
対象リポジトリを所有するアカウントまたは Organization を選択します。
Only select repositories を選択します。
Minara に許可するリポジトリを選択します。
Install を選択します。Request と表示された場合は、Organization Owner の承認を待ちます。

インストールはリポジトリへのアクセス範囲を付与します。Minara でのサインインは、そのインストールを通して操作するユーザーを認証します。両方が必要です。

4. Client ID をコピーする

GitHub App の設定ページに戻り、Client ID をコピーします。App ID ではありません。

Iv1.8a61f9b3a7aba766

Client ID は公開されるアプリ情報です。Minara の Device Flow では Client Secret と GitHub App private key は不要です。

5. Minara の開発ビルドを設定する

リポジトリ直下の .env に Client ID を追加します。

MINARA_GITHUB_APP_CLIENT_ID=Iv1.8a61f9b3a7aba766

例を GitHub からコピーした値に置き換えます。Minara Desktop を完全に終了して再起動します。

pnpm dev:desktop

製品版は公開 Client ID を製品設定として同梱し、利用者ごとの App 登録を不要にします。

6. Minara で GitHub に接続する

Minara の Settings を開きます。
Git アクセス を選択します。
Connect GitHub で Connect GitHub を選択します。
GitHub のデバイス認証ページでワンタイムコードを入力します。
GitHub アカウントを確認し、App を承認します。
Minara に戻り、アカウントが Ready と表示されることを確認します。

確認

Git アクセス で GitHub アカウントが Ready になっていることを確認します。
対象 remote が SSH または HTTPS で github.com を参照していることを確認します。
Coding に branch の fetch または push を依頼します。
Pull Request では、App のインストールと Pull requests: Read and write を確認します。

トラブルシューティング

症状	対処
Connect GitHub が使えない	`MINARA_GITHUB_APP_CLIENT_ID` を設定し、Desktop を完全に再起動します
Client ID が無効と表示される	App ID や Client Secret ではなく Client ID をコピーします
デバイス認証ページが表示されない	GitHub App で Device Flow を有効にします
認証後に 403 または 404 が返る	App を対象リポジトリにインストールし、保留中の Organization 承認を完了します
Push が拒否される	Contents を Read and write に変更し、権限変更を承認します
Pull Request を作成できない	Pull requests を Read and write にします

セキュリティモデル

ユーザー access token は暗号化された認証情報ストアに保存されます。SQLite や会話には保存しません。
Device code には有効期限があり、1 回だけ使えます。
App はインストール時に選択したリポジトリだけにアクセスできます。
ユーザー権限と App 権限の両方が適用されます。
GitHub profile を切断すると、Minara は保存した認証情報を削除します。