デプロイキー

デプロイキーを使用して、GitLabでホストされているリポジトリにアクセスします。ほとんどの場合、デプロイキーを使用して、ビルドサーバーや継続的インテグレーション（CI）サーバーなどの外部ホストからリポジトリにアクセスします。

必要に応じて、代わりにデプロイトークンを使用してリポジトリにアクセスすることもできます。

外部認証が有効になっている場合、デプロイキーはGitオペレーションに使用できません。

スコープ

デプロイキーには、作成時に定義されたスコープがあります。

• プロジェクトデプロイキー: アクセスは、選択したプロジェクトに限定されます。
• パブリックデプロイキー: GitLabインスタンス内の任意のプロジェクトにアクセスを許可できます。各プロジェクトへのアクセスは、少なくともメンテナーロールを持つユーザーによって許可される必要があります。

デプロイキーのスコープは、作成後に変更できません。

権限

デプロイキーには、作成時に権限レベルが与えられます。

• 読み取り専用: 読み取り専用のデプロイキーは、リポジトリから読み取るだけです。
• 読み取り/書き込み: 読み取り/書き込みデプロイキーは、リポジトリから読み取り、書き込みできます。

デプロイキーの権限レベルは、作成後に変更できます。プロジェクトのデプロイキーの権限を変更すると、現在のプロジェクトにのみ適用されます。

デプロイキーを使用するプッシュが追加のプロセスをトリガーする場合、キーの作成者は認証される必要があります。例:

• デプロイキーを使用して保護ブランチにコミットをプッシュする場合、デプロイキーの作成者はブランチへのアクセス権を持っている必要があります。
• デプロイキーを使用してCI/CDパイプラインをトリガーするコミットをプッシュする場合、デプロイキーの作成者は、保護環境やシークレット変数を含むCI/CDリソースへのアクセス権を持っている必要があります。

セキュリティ上の注意点

デプロイキーは、GitLabとの非人的なインタラクションを容易にするためのものです。たとえば、デプロイキーを使用して、組織内のサーバーで自動的に実行されるスクリプトに権限を付与できます。

サービスアカウントを使用し、サービスアカウントでデプロイキーを作成する必要があります。別のユーザーアカウントを使用してデプロイキーを作成した場合、そのユーザーには、デプロイキーが失効するまで永続する権限が付与されます。

さらに、次のようになります。

• デプロイキーのオーナーがブロックされたり、インスタンスから削除された場合、デプロイキーは却下されます。リポジトリ操作（プルやプッシュを含む）には使用できません。
• デプロイキーが保護ブランチルールで指定されている場合、デプロイキーの作成者は:
  • 保護ブランチ、およびデプロイキー自体へのアクセスを獲得します。
  • デプロイキーに読み取り/書き込み権限がある場合、保護ブランチにプッシュできます。これは、ブランチがすべてのユーザーからの変更に対して保護されている場合でも当てはまります。

すべての機密情報と同様に、シークレットへのアクセスを必要とするユーザーのみがそれを読み取ることができるようにする必要があります。人的なインタラクションでは、パーソナルアクセストークンなどのユーザーに関連付けられた認証情報を使用します。

潜在的なシークレット漏洩を検出するために、監査イベント機能を使用できます。

デプロイキーの表示

プロジェクトで使用可能なデプロイキーを表示するには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > リポジトリを選択します。
3. デプロイキーを展開します。

使用可能なデプロイキーが一覧表示されます:

• 有効なデプロイキー: プロジェクトへのアクセス権を持つデプロイキー。
• 秘密にアクセスできるデプロイキー: プロジェクトへのアクセス権を持たないプロジェクトデプロイキー。
• パブリックアクセスが可能なデプロイキー: プロジェクトへのアクセス権を持たないパブリックデプロイキー。

GitLab CLIはglab deploy-key listコマンドを提供します。

プロジェクトデプロイキーの作成

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。
• SSHキーペアを生成します。リポジトリへのアクセスを必要とするホストに、プライベートSSHキーを配置します。

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > リポジトリを選択します。
3. デプロイキーを展開します。
4. 新しいキーを追加を選択します。
5. フィールドに入力します。
6. オプション。read-write権限を付与するには、このキーに書き込み権限を与えるチェックボックスをオンにします。
7. オプション。有効期限を更新します。

プロジェクトデプロイキーは、作成時に有効になります。変更できるのは、プロジェクトデプロイキーの名前と権限のみです。デプロイキーが複数のプロジェクトで有効になっている場合、デプロイキー名を変更することはできません。

GitLab CLIはglab deploy-key addコマンドを提供します。

パブリックデプロイキーの作成

前提条件:

• インスタンスへの管理者アクセス権を持っている必要があります。
• SSHキーペアを生成する必要があります。
• リポジトリへのアクセスを必要とするホストに、プライベートSSHキーを配置する必要があります。

パブリックデプロイキーを作成するには:

1. 右上隅で、管理者を選択します。
2. デプロイキーを選択します。
3. 新しいデプロイキーを選択します。
4. フィールドに入力します。
   • 名前には意味のある説明を使用します。たとえば、パブリックデプロイキーを使用する外部ホストまたはアプリケーションの名前を含めます。

変更できるのは、パブリックデプロイキーの名前のみです。

パブリックデプロイキーへのプロジェクトアクセスの許可

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。

パブリックデプロイキーにプロジェクトへのアクセスを許可するには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > リポジトリを選択します。
3. デプロイキーを展開します。
4. パブリックアクセスが可能なデプロイキーを選択します。
5. キーの行で、有効を選択します。
6. パブリックデプロイキーに読み取り/書き込み権限を付与するには:
   1. キーの行で、編集（ ）を選択します。
   2. このキーに書き込み権限を与えるチェックボックスをオンにします。

デプロイキーのプロジェクトアクセス権限の編集

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。

デプロイキーのプロジェクトアクセス権限を編集するには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > リポジトリを選択します。
3. デプロイキーを展開します。
4. キーの行で、編集（ ）を選択します。
5. このキーに書き込み権限を与えるチェックボックスをオンまたはオフにします。

デプロイキーのプロジェクトアクセスの取り消し

プロジェクトへのデプロイキーのアクセスを取り消すには、そのキーを無効にできます。デプロイキーに依存するサービスは、キーが無効になると動作を停止します。

前提条件:

• プロジェクトのメンテナーまたはオーナーロールが必要です。

デプロイキーを無効にするには:

1. 上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
2. 設定 > リポジトリを選択します。
3. デプロイキーを展開します。
4. キーの行で、無効（ ）を選択します。

無効にされたときのデプロイキーの動作は、以下によって異なります:

• キーがパブリックにアクセス可能な場合、プロジェクトから削除されますが、パブリックアクセスが可能なデプロイキータブでは引き続き使用できます。
• キーがプライベートにアクセス可能で、このプロジェクトでのみ使用されている場合、削除されます。
• キーがプライベートにアクセス可能で、他のプロジェクトでも使用されている場合、プロジェクトから削除されますが、秘密にアクセスできるデプロイキータブでは引き続き使用できます。

関連トピック

• GitLab CLIのデプロイキー用コマンド

トラブルシューティング

デプロイキーが却下されました

デプロイキーは以下のいずれかの場合に却下されます:

• キーのオーナーがブロックされている場合。
• キーの有効期限が切れている場合。

デプロイキーが却下されると、プルやプッシュを含むすべてのリポジトリ操作に使用できなくなります。

この問題を解決するには、次の手順に従います:

• キーのオーナーがブロックされている場合、ユーザーのブロックを解除するか、キーのオーナーをアクティブユーザーに変更します。
• キーの有効期限が切れている場合は、新しいデプロイキーを作成します。

デプロイキーが保護ブランチにプッシュできない

デプロイキーが保護ブランチへのプッシュに失敗するシナリオがいくつかあります。

• デプロイキーに関連付けられているオーナーが、保護ブランチのプロジェクトへのメンバーシップを持っていません。
• デプロイキーに関連付けられているオーナーのプロジェクトメンバーシップ権限が、プロジェクトコードの表示に必要な権限よりも低くなっています。
• デプロイキーにプロジェクトの読み取り/書き込み権限がありません。
• デプロイキーが失効しました。
• 保護ブランチのプッシュとマージを許可セクションでなしが選択されています。

このイシューは、すべてのデプロイキーがアカウントに関連付けられているために発生します。アカウントの権限は変更される可能性があるため、動作していたデプロイキーが突然保護ブランチにプッシュできなくなるシナリオが発生する可能性があります。

このイシューを解決するには、独自のユーザーではなく、プロジェクトサービスアカウントユーザーのデプロイキーを作成するために、デプロイキーAPIを使用できます。

1. サービスアカウントユーザーを作成します。

2. そのサービスアカウントユーザーのパーソナルアクセストークンを作成します。このトークンには、少なくともapiスコープが必要です。

3. サービスアカウントユーザーをプロジェクトに招待します。

4. デプロイキーAPIを使用して、サービスアカウントユーザーのデプロイキーを作成します:

   curl --request POST --header "PRIVATE-TOKEN: <service_account_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' \
     --url "https://gitlab.example.com/api/v4/projects/5/deploy_keys/"

非メンバーおよびブロックされたユーザーに関連付けられたデプロイキーの特定

非メンバーまたはブロックされたユーザーに属するキーを見つける必要がある場合は、Railsコンソールを使用して、次のようなスクリプトを使用して使用できないデプロイキーを特定できます:

DeployKeysProject.with_write_access.find_each do |deploy_key_mapping|
  project = deploy_key_mapping.project
  deploy_key = deploy_key_mapping.deploy_key
  user = deploy_key.user

  access_checker = Gitlab::DeployKeyAccess.new(deploy_key, container: project)

  # can_push_for_ref? tests if deploy_key can push to default branch, which is likely to be protected
  can_push = access_checker.can_do_action?(:push_code)
  can_push_to_default = access_checker.can_push_for_ref?(project.repository.root_ref)

  next if access_checker.allowed? && can_push && can_push_to_default

  if user.nil? || user.ghost?
    username = 'none'
    state = '-'
  else
    username = user.username
    user_state = user.state
  end

  puts "Deploy key: #{deploy_key.id}, Project: #{project.full_path}, Can push?: " + (can_push ? 'YES' : 'NO') +
       ", Can push to default branch #{project.repository.root_ref}?: " + (can_push_to_default ? 'YES' : 'NO') +
       ", User: #{username}, User state: #{user_state}"
end

デプロイキーのオーナーの設定

デプロイキーは特定のユーザーに属しており、そのユーザーがブロックされたり、インスタンスから削除されたりすると却下されます。ユーザーが削除されたときにデプロイキーが動作し続けるようにするには、そのオーナーをアクティブユーザーに変更します。

デプロイキーのフィンガープリントがある場合は、次のコマンドを使用して、デプロイキーに関連付けられているユーザーを変更できます。

k = Key.find_by(fingerprint: '5e:51:92:11:27:90:01:b5:83:c3:87:e3:38:82:47:2e')
k.user_id = User.find_by(username: 'anactiveuser').id
k.save()