SSHエージェントのフォワーディング、OAuthトークンでのHTTPS、デプロイキー、マシンユーザを使ってデプロイメントスクリプトを自動化する際に、サーバー上のSSHキーを管理できます。
SSHエージェントのフォワーディング
多くの場合、特にプロジェクトの開始時には、SSHエージェントのフォワーディングが最も素早くシンプルに使える方法です。 エージェントのフォワーディングでは、ローカルの開発コンピュータで使うのと同じSSHキーを使います。
SSH エージェント転送の長所
- 新しいキーを生成したり追跡したりしなくていい。
- キーの管理は不要。ユーザはローカルと同じ権限をサーバーでも持つ。
- サーバーにキーは保存されないので、サーバーが侵害を受けた場合でも、侵害されたキーを追跡して削除する必要はない。
SSH エージェント転送の短所
- ユーザーは、デプロイに SSH 接続する必要があります。自動デプロイ プロセスは使用できません。
- SSHエージェントのフォワーディングは、Windowsのユーザが実行するのが面倒。
SSH エージェント転送を設定する
- エージェントのフォワーディングをローカルでオンにしてください。 詳細については、SSH エージェントの転送に関するガイドを参照してください。
- エージェントフォワーディングを使用するように、デプロイスクリプトを設定してください。 たとえば、bash スクリプトでは、エージェントの転送を有効にすると、次のようになります:
ssh -A serverA 'bash -s' < deploy.sh
OAuthトークンを使ったHTTPSでのクローニング
SSH キーを使用しない場合は、OAuth トークンで HTTPS を使用できます。
OAuth トークンを使った HTTPS でのクローニングの長所
-
サーバーにアクセスできる人なら、リポジトリをデプロイできる。
-
ユーザはローカルのSSH設定を変更する必要がない。
-
複数のトークン(ユーザごと)が必要ない。サーバーごとに1つのトークンで十分。
-
トークンはいつでも取り消しできるので、本質的には使い捨てのパスワードにすることができる。
-
新しいトークンの生成は、OAuth API を使用して簡単にスクリプト化できます。
OAuth トークンを使った HTTPS でのクローニングの短所
- トークンを確実に正しいアクセススコープで設定しなければならない。
- トークンは本質的にはパスワードであり、パスワードと同じように保護しなければならない。
OAuth トークンを使った HTTPS でのクローニングを設定する
personal access token の作成に関するガイドを参照してください。
デプロイ キー
デプロイ キーを使用すると、お使いの GitHub Enterprise Server インスタンス のリポジトリからサーバーにプロジェクトを起動できます。デプロイ キーは、単一のリポジトリへのアクセス権を付与する SSH キーです。 GitHub Enterprise Server は個人アカウントの代わりに、リポジトリに直接キーのパブリックな部分をアタッチし、キーのプライベートな部分はサーバーに残ります。 詳しくは、「デプロイメントを配信する」を参照してください。
書き込みアクセス権を持つキーをデプロイすれば、管理アクセス権を持つOrganizationのメンバー、あるいは個人リポジトリのコラボレータと同じアクションを行えます。 詳細については、「Organizationのリポジトリロール」および「個人アカウントのリポジトリの権限レベル」を参照してください。
デプロイ キーの長所
- リポジトリとサーバーにアクセスできる人は、誰でもプロジェクトをデプロイできる。
- ユーザはローカルのSSH設定を変更する必要がない。
- デプロイ キーは既定では読み取り専用ですが、リポジトリに追加するときに書き込みアクセス権を付与することができます。
デプロイ キーの短所
- デプロイキーは単一のリポジトリに対するアクセスだけを許可できる。 より複雑なプロジェクトは、同じサーバーからプルする多くのリポジトリを持っていることがある。
- デプロイキーは通常パスフレーズで保護されていないので、サーバーが侵害されると簡単にキーにアクセスされることになる。
- デプロイ キーは、特定のユーザーではなくリポジトリに関連付けられているため、デプロイ キーを作成したユーザーがリポジトリから削除されても、引き続きアクティブです。
デプロイ キーを設定する
-
サーバーで
ssh-keygen
手順を実行し、生成された公開キーと秘密 RSA キーのペアを保存する場所を覚えておいてください。 -
GitHub で、リポジトリのメイン ページに移動します。
-
リポジトリ名の下にある [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [設定] をクリックします。
-
サイドバーにある [Deploy Keys] (キーのデプロイ) をクリックします。
-
[Add deploy key] (デプロイ キーの追加) をクリックします。
-
[タイトル] フィールドにタイトルを入力します。
-
[キー] フィールドに公開キーを貼り付けます。
-
このキーにリポジトリへの書き込みアクセス権を付与する場合は、 [書き込みアクセスを許可する] を選択します。 書き込みアクセス権を持つデプロイキーを使うと、リポジトリにデプロイメントのプッシュができるようになります。
-
[キーの追加] をクリックします。
REST API を使用して、デプロイ キーを作成することもできます。 詳しくは、「デプロイ キー用の REST API エンドポイント」を参照してください。
1つのサーバー上で複数のリポジトリを利用する
1つのサーバー上で複数のリポジトリを使うなら、それぞれのリポジトリに対して専用のキーペアを生成しなければなりません。 複数のリポジトリでデプロイキーを再利用することはできません。
サーバーの SSH 構成ファイル (通常 ~/.ssh/config
) に、各リポジトリのエイリアス エントリを追加します。 次に例を示します。
Host my-GHE-hostname.com-repo-0
Hostname my-GHE-hostname.com
IdentityFile=/home/user/.ssh/repo-0_deploy_key
Host my-GHE-hostname.com-repo-1
Hostname my-GHE-hostname.com
IdentityFile=/home/user/.ssh/repo-1_deploy_key
Host my-GHE-hostname.com-repo-0
- リポジトリのエイリアス。Hostname my-GHE-hostname.com
- エイリアスで使用するホスト名を構成します。IdentityFile=/home/user/.ssh/repo-0_deploy_key
- 秘密キーをエイリアスに割り当てます。
こうすれば、ホスト名のエイリアスを使ってSSHでリポジトリとやりとりできます。この場合、このエイリアスに割り当てられたユニークなデプロイキーが使われます。 次に例を示します。
git clone git@my-GHE-hostname.com-repo-1:OWNER/repo-1.git
GitHub App インストール アクセス トークン
サーバーが 1 つまたは複数の組織にわたるリポジトリにアクセスする必要がある場合、GitHub App を使用して必要なアクセスを定義し、その GitHub App から_厳密にスコープが設定された_インストール アクセス トークンを生成できます。 インストール アクセス トークンは単一または複数のリポジトリをスコープとすることができ、アクセス許可を細かく設定できます。 たとえば、リポジトリのコンテンツへの読み取り専用アクセス権を持つトークンを生成できます。
GitHub Apps は GitHub Enterprise Server で主役級の存在なので、インストール アクセス トークンはあらゆる GitHub ユーザーから切り離されていて、「サービストークン」に相当します。 さらに、インストール アクセス トークンには、実行される組織の規模に応じてスケーリングされる専用のレート制限があります。 詳細については、「GitHub Apps のレート制限」を参照してください。
インストール アクセス トークンの長所
- 権限設定と有効期限 (1時間、またはAPIで手動で取り消された場合にはそれ以下) が明確に定義された、スコープが厳格なトークン。
- 組織の規模に従って拡大する、独自のレート制限。
- GitHub ユーザー ID から切り離されているため、ライセンス シートは使用されません。
- パスワードが付与されないので、直接サインインされない。
インストール アクセス トークンの短所
- GitHub App を作成するには、追加のセットアップが必要です。
- インストール アクセス トークンは 1 時間後に期限切れになるので、再生成する必要がある (通常はコードを使用して、オンデマンドで行う)。
インストール アクセス トークンを設定する
- GitHub App をパブリックとプライベートのどちらにするかを決定します。 GitHub App が組織内のリポジトリのみで動作する場合は、プライベートに設定した方がいいでしょう。
- リポジトリの内容の読み取り専用アクセスなど、GitHub App が必要とするアクセス許可を決定します。
- 組織の設定ページから GitHub App を作成します。 詳細については、「GitHub App を作成する」を参照してください。
- GitHub App
id
をメモします。 - GitHub App の秘密キーを生成してダウンロードし、安全な方法で保存します。 詳細については、「秘密キーを生成する」を参照してください。
- 動作させたいリポジトリに GitHub App をインストールします。必要に応じて、組織の全リポジトリに GitHub App をインストールしても構いません。
- GitHub App と、それがアクセスできる組織リポジトリの間の接続を表す
installation_id
を特定します。 GitHub App と組織のペアのそれぞれには、最大で 1 つのinstallation_id
があります。 「認証されたアプリの組織のインストールを取得する」を使用してこのinstallation_id
を識別できます。 これには、JWT を使用した GitHub App としての認証が必要です。詳細については、「GitHub App としての認証」を参照してください。 - 対応する REST API エンドポイントを使用して、インストール アクセス トークンを生成します。「アプリのインストール アクセス トークンを作成する」を参照してください。 これには、JWT を使用した GitHub App としての認証が必要です。詳細については、「GitHub App としての認証」と「インストールとしての認証」を参照してください。
- このインストール アクセス トークンを使用して、REST または GraphQL API、あるいは Git クライアント経由でリポジトリとやり取りします。
詳しくは、「GitHub アプリのインストール アクセス トークンの生成」を参照してください。
マシンユーザ
サーバーが複数のリポジトリにアクセスする必要がある場合は、お使いの GitHub Enterprise Server インスタンス 上で新しいアカウントを作成し、自動化専用に使用される SSH キーをアタッチすることができます。 お使いの GitHub Enterprise Server インスタンス のこのアカウントは人間には使用されないため、_マシン ユーザー_と呼ばれます。 マシン ユーザーを個人リポジトリの コラボレーター (読み取りと書き込みアクセス権の付与)、組織リポジトリの 外部コラボレーター (読み取り、書き込み、または管理者アクセス権の付与)、または自動化する必要があるリポジトリへのアクセス権を持つ チーム (チームのアクセス許可の付与) として追加できます。
マシン ユーザーの長所
- リポジトリとサーバーにアクセスできる人は、誰でもプロジェクトをデプロイできる。
- (人間の)ユーザがローカルのSSH設定を変更する必要がない。
- 複数のキーは必要ない。サーバーごとに1つでよい。
マシン ユーザーの短所
- 組織だけがマシンユーザをリードオンリーのアクセスにできる。 個人リポジトリは、常にコラボレータの読み書きアクセスを許可する。
- マシンユーザのキーは、デプロイキーのように、通常パスフレーズで保護されない。
マシン ユーザーを設定する
- サーバーで
ssh-keygen
手順を実行し、公開キーをマシン ユーザー アカウントにアタッチします。 - マシンユーザアカウントに自動化したいリポジトリへのアクセスを付与してください。 これを行うには、アカウントを コラボレーター として、外部コラボレーター として、または組織内の チーム に追加します。