デプロイキーの管理

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 Enterprise Server インスタンスで、リポジトリのメインページへ移動します。
リポジトリ名の下にある [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウンメニューを選び、 [設定] をクリックします。
サイドバーにある [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 手順を実行し、公開キーをマシンユーザーアカウントにアタッチします。
マシンユーザアカウントに自動化したいリポジトリへのアクセスを付与してください。これを行うには、アカウントをコラボレーターとして、外部コラボレーターとして、または組織内のチームに追加します。

参考資料

通知の構成

デプロイキーの管理

この記事の内容