# GitHub App をインストールする

> Latchkey の GitHub App のインストールの仕組み、なぜ組織アカウントが必要なのか、どの権限を使うのか、そして失敗したインストールの修正方法を説明します。

Source: https://latchkey.dev/ja/documentation/install-the-github-app

## Summary

- Get started カードの **Connect GitHub** ステップから GitHub の **組織** にインストールします。インストールした人がワークスペースの owner になります。
- 個人アカウントへのインストールは拒否され、自動的に削除されます。
- アプリはワークフローの実行と YAML を読み取り、webhook を受信し、あなたの操作時のみ PR を開き、自身のランナーグループを管理します。

Latchkey は GitHub App を通じて GitHub に接続します。そのインストールは、他のすべてが依存する 1 回限りのセットアップステップです。webhook、分析、AI の推奨事項、マネージドランナーはすべてアプリを通じて流れます。そのため、何かが切断されているように見えるときに最初に確認すべきものでもあります。アプリが存在しない、または間違った組織に置かれている場合、下流のすべての機能が一度に症状を示します。

## オンボーディング中にインストールする

通常の道のりは Get started カードのステップ 1、**Connect GitHub** です。クリックすると、GitHub が [GitHub 上の Latchkey アプリの掲載ページ](https://github.com/apps/latchkey-analytics-ci-cd-monitor) からインストールフローを開きます。監視したい **組織** を選んで確認します。GitHub があなたを Latchkey に戻すと、インストールがワークスペースにリンクされ、セットアップはリポジトリ選択へと続きます。

> **誰がワークスペースの owner になるか**
> アプリをインストールした人が、Latchkey でワークスペースの owner としてリンクされます。ワークスペースごとに owner は 1 人だけで、所有権は後で「所有権の移譲」で引き渡せます。そのため、請求とチーム管理を所有すべきアカウントでインストールしてください。[チームとロール](/documentation/team-and-roles) をご覧ください。

## 組織アカウントが必須です

Latchkey は GitHub の **組織** アカウントのみをサポートします。アプリが個人 (ユーザー) アカウントにインストールされた場合、Latchkey はそれを拒否します。インストールは GitHub から自動的にアンインストールされ、ダッシュボードには「You'll need a GitHub organization」というエラーが表示されるので、組織で再試行できます。個人アカウントしかない場合は、まず [GitHub の組織を作成](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) し (無料です)、リポジトリをそこへ移すか作成してください。

## 組織を作成してリポジトリを移動する

個人アカウントしかありませんか？既存のリポジトリを手放す必要はありません。無料の組織を作成し、そこにリポジトリを移動して、再接続してください。数分で完了し、履歴、issue、スターもそのまま引き継がれます。

1. **無料の組織を作成する** [github.com/account/organizations/new](https://github.com/account/organizations/new) にアクセスして組織を作成します。Latchkey には **Free** プランで十分です。チーム名、プロジェクト名、またはハンドル名を付けてください。GitHub 公式のガイドは [Creating a new organization from scratch](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch) です。
2. **リポジトリを組織に移動する** GitHub のリポジトリで **Settings → General → Danger Zone → Transfer ownership** を開き、新しい組織に移譲します。移譲してもコミット履歴、issue、プルリクエスト、スターは維持され、GitHub が古い URL をリダイレクトするため、既存のクローンやリンクはそのまま使えます。[Transferring a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository) を参照してください。ゼロから始めたい場合は、代わりに組織内に新しいリポジトリを直接作成してください。
3. **Latchkey を再接続する** Latchkey に戻り、Get started カードでもう一度 **Connect GitHub** をクリックして、今度は自分の **組織** を選択します。インストールがワークスペースにリンクされ、セットアップはリポジトリ選択に進みます。

## アプリがアクセスできるもの

平たく言えば、Latchkey アプリは次のことを行います。

- **ワークフロー実行とジョブのメタデータを読み取ります** (名前、タイミング、ステータス、ランナーラベル)。これがコスト、パフォーマンス、信頼性のダッシュボードの元となる素材です。
- **`.github/workflows/` 配下のワークフロー YAML ファイルを読み取ります**。これにより AI がそれらを分析し、最適化 PR が編集するまさにそのファイルに対して具体的な変更を提案できます。
- **ワークフローイベントの webhook を受信します**。これによりダッシュボードがリアルタイムで最新に保たれます。ポーリングや更新をするものが何もないのもこのためです。
- **あなたが求めたときのみ、あなたに代わってプルリクエストを開きます**。最適化の推奨事項の適用、または自己修復の修正提案の場合です。これらの PR は常にあなたのレビュー用で、自動的にマージされるものはなく、fork からのプルリクエストが触れられることは決してありません。
- **組織内で自身のランナーグループを管理します**。これにより `runs-on: latchkey-*` のジョブをマネージドランナーへルーティングできます。これはリポジトリの内容ではなく、組織の CI 配管です。

アプリが行わないこと: Latchkey はワークフローファイル以外のアプリケーションのソースコードを読み取らず、secret や環境変数の値を読むことも決してありません。セキュリティチームが、ランナーの隔離やデータ削除を含む全体像を求める場合は、[セキュリティと GitHub の権限](/documentation/security-and-permissions) を紹介してください。セキュリティレビューに直接答えられるように書かれています。

## インストールがうまくいかない場合

- **間違ったアカウントにインストールした場合:** 個人アカウントだった場合、Latchkey はすでにインストールを削除しています。組織で再試行するだけです。間違った組織だった場合は、GitHub でその組織からアプリをアンインストールし (Settings、GitHub Apps)、正しい組織にインストールしてください。アプリが現在どこにあるかを確認するには、各組織の Settings、GitHub Apps ページを確認します。Latchkey はインストールされている場所ならどこでもリストに表示されます。
- **インストール途中でタブを閉じた場合:** もう一度サインインすると、Get started カードが中断したところから再開します。先に元に戻す必要はありません。
- **インストール権限がない場合:** 組織に GitHub App をインストールするには owner または admin 権限が必要です。組織の owner にアプリのインストールを依頼するか、admin 権限を付与してもらい、オンボーディングから再試行してください。

## よくある質問

### 誰がワークスペースの owner になりますか？

GitHub App をインストールした人が、ワークスペースの owner としてリンクされます。ワークスペースごとに owner は 1 人だけで、owner は後で「所有権の移譲」でワークスペースを別のメンバーに引き渡せます。詳細は [チームとロール](/documentation/team-and-roles) にあります。

### Latchkey を複数の組織にインストールできますか？

はい。各インストールは、独自のプラン、チーム、リポジトリ、データを持つ独自のワークスペースを得ます。ダッシュボードのサイドバーにあるワークスペース切り替えで、所属するワークスペース間を移動でき、Latchkey はサインインをまたいで最後に使用したワークスペースを記憶します。

### インストールするには GitHub 組織の owner でなければなりませんか？

組織に対する owner または admin 権限が必要です。どちらもない場合は、組織の owner にアプリのインストールを依頼するか、admin 権限を付与してもらってください。

### アプリをインストールするとリポジトリに何か変更が加わりますか？

いいえ。インストールするエージェントはなく、あなたが決めるまでワークフローへの変更もありません。Latchkey が書き込むのは、あなたがレビューできるプルリクエストを通じてのみです。あなたが適用する最適化、または自己修復の修正提案です。[セキュリティと GitHub の権限](/documentation/security-and-permissions) をご覧ください。

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt