ドキュメントメニュー
マネージドランナー
ワークフローファイル
GitHub App をインストールする
Latchkey の GitHub App のインストールの仕組み、どのような場合に組織アカウントが必要なのか、どの権限を使うのか、そして失敗したインストールの修正方法を説明します。
要点
- Get started カードの Connect GitHub ステップから GitHub の 組織 にインストールします。インストールした人がワークスペースの owner になります。
- 個人アカウントも接続でき、Latchkey CI を実行できます。Latchkey on GH (GitHub Actions で動く Latchkey のマネージドランナー) には 組織 が必要です。
- アプリはワークフローの実行と YAML を読み取り、webhook を受信し、あなたの操作時のみ PR を開き、自身のランナーグループを管理します。
Latchkey は GitHub App を通じて GitHub に接続します。そのインストールは、他のすべてが依存する 1 回限りのセットアップステップです。webhook、分析、AI の推奨事項、マネージドランナーはすべてアプリを通じて流れます。そのため、何かが切断されているように見えるときに最初に確認すべきものでもあります。アプリが存在しない、または間違った組織に置かれている場合、下流のすべての機能が一度に症状を示します。
オンボーディング中にインストールする#
- 01GitHub を接続Get started カードから GitHub へ移動します
- 02組織を選択または個人アカウント (Latchkey CI 用)
- 03Latchkey へ戻るインストールがワークスペースにリンクされます
- 04リポジトリを選択セットアップはリポジトリ選択へ続きます
通常の道のりは Get started カードのステップ 1、Connect GitHub です。クリックすると、GitHub が GitHub 上の Latchkey アプリの掲載ページ からインストールフローを開きます。監視したい 組織 を選んで確認します。GitHub があなたを Latchkey に戻すと、インストールがワークスペースにリンクされ、セットアップはリポジトリ選択へと続きます。
どのアカウントにインストールするか#
Latchkey on GH には、GitHub の 組織 にインストールされたアプリが必要です。個人 (ユーザー) アカウントも接続でき、Latchkey CI を実行できます: ダッシュボードでリポジトリを選択してから、ワークフローファイルを .latchkey/workflows/ の下にコミットしてプッシュしてください。ファイルについては ワークフローファイル で説明しています。個人アカウントのリポジトリで Latchkey on GH を使うには、次のセクションのとおり、まずリポジトリを組織に移動してください。
組織を作成してリポジトリを移動する#
個人アカウントのリポジトリで Latchkey on GH を使いたいですか？Latchkey on GH には組織が必要ですが、既存のリポジトリを手放す必要はありません。無料の組織を作成し、そこにリポジトリを移動して、組織を接続してください。数分で完了し、履歴、issue、スターもそのまま引き継がれます。
無料の組織を作成する
github.com/
リポジトリを組織に移動する
GitHub のリポジトリで Settings → General → Danger Zone → Transfer ownership を開き、新しい組織に移譲します。移譲してもコミット履歴、issue、プルリクエスト、スターは維持され、GitHub が古い URL をリダイレクトするため、既存のクローンやリンクはそのまま使えます。Transferring a repository を参照してください。ゼロから始めたい場合は、代わりに組織内に新しいリポジトリを直接作成してください。
組織を接続する
Latchkey に戻り、Get started カードで Connect GitHub をクリックして、自分の 組織 を選択します。このログインにすでに接続済みのワークスペースがある場合は、サイドバーのワークスペースメニューを開いて Add workspace を選び、新しいワークスペースの Get started カードから組織を接続してください。組織には専用のワークスペースが作られます。無料トライアルはおひとりにつき 1 回です: 2 つ目のワークスペースにはトライアルがなく、プランを購読すると実行できるようになります。インストールはそのワークスペースにリンクされ、セットアップはリポジトリ選択に進みます。
アプリがアクセスできるもの#
平たく言えば、Latchkey アプリは次のことを行います。
- ワークフロー実行とジョブのメタデータを読み取ります (名前、タイミング、ステータス、ランナーラベル)。これがコスト、パフォーマンス、信頼性のダッシュボードの元となる素材です。
.github/workflows/配下のワークフロー YAML ファイルを読み取ります。これにより AI がそれらを分析し、最適化 PR が編集するまさにそのファイルに対して具体的な変更を提案できます。- ワークフローイベントの webhook を受信します。これによりダッシュボードがリアルタイムで最新に保たれます。ポーリングや更新をするものが何もないのもこのためです。
- あなたが求めたときのみ、あなたに代わってプルリクエストを開きます。最適化の推奨事項の適用、または自己修復の修正提案の場合です。これらの PR は常にあなたのレビュー用で、自動的にマージされるものはなく、fork からのプルリクエストが触れられることは決してありません。
- 組織内で自身のランナーグループを管理します。これにより
runs-on: latchkey-*のジョブをマネージドランナーへルーティングできます。これはリポジトリの内容ではなく、組織の CI 配管です。
アプリが行わないこと: Latchkey はワークフローファイル以外のアプリケーションのソースコードを読み取らず、secret や環境変数の値を読むことも決してありません。セキュリティチームが、ランナーの隔離やデータ削除を含む全体像を求める場合は、セキュリティと GitHub の権限 を紹介してください。セキュリティレビューに直接答えられるように書かれています。
インストールがうまくいかない場合#
- 間違ったアカウントにインストールした場合: 間違った組織だった場合は、GitHub でその組織からアプリをアンインストールし (Settings、GitHub Apps)、正しい組織にインストールしてください。アプリが現在どこにあるかを確認するには、各組織の Settings、GitHub Apps ページと、ご自身のアカウントの Settings、Applications ページを確認します。Latchkey はインストールされている場所ならどこでもリストに表示されます。
- インストール途中でタブを閉じた場合: もう一度サインインすると、Get started カードが中断したところから再開します。先に元に戻す必要はありません。
- インストール権限がない場合: 組織に GitHub App をインストールするには owner または admin 権限が必要です。組織の owner にアプリのインストールを依頼するか、admin 権限を付与してもらい、オンボーディングから再試行してください。
よくある質問#
誰がワークスペースの owner になりますか？
GitHub App をインストールした人が、ワークスペースの owner としてリンクされます。ワークスペースごとに owner は 1 人だけで、owner は後で「所有権の移譲」でワークスペースを別のメンバーに引き渡せます。詳細は チームとロール にあります。
Latchkey を複数の組織にインストールできますか？
はい。各インストールは、独自のプラン、チーム、リポジトリ、データを持つ独自のワークスペースを得ます。サイドバーの先頭にあるワークスペースメニューで、所属するワークスペース間を移動でき、Latchkey はサインインをまたいで最後に使用したワークスペースを記憶します。
インストールするには GitHub 組織の owner でなければなりませんか？
組織に対する owner または admin 権限が必要です。どちらもない場合は、組織の owner にアプリのインストールを依頼するか、admin 権限を付与してもらってください。
アプリをインストールするとリポジトリに何か変更が加わりますか？
いいえ。インストールするエージェントはなく、あなたが決めるまでワークフローへの変更もありません。Latchkey が書き込むのは、あなたがレビューできるプルリクエストを通じてのみです。あなたが適用する最適化、または自己修復の修正提案です。セキュリティと GitHub の権限 をご覧ください。