正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

SSHキーを使用してGitLabと通信する

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

Gitは分散型バージョン管理システムです。ローカルで作業してから、変更をサーバーに共有またはプッシュできます。この場合、プッシュ先のサーバーはGitLabです。

GitLabはSSHプロトコルを使用して、Gitと安全に通信します。SSHキーを使用してGitLabリモートサーバーに対して認証する場合、毎回ユーザー名とパスワードを入力する必要はありません。

SSHキーとは

SSHは、公開キーと秘密キーの2つのキーを使用します。

  • 公開キーは配布できます。
  • 秘密キーは保護する必要があります。

公開キーをアップロードしても、機密データが漏洩することはありません。SSH公開キーをコピーまたはアップロードする際に、誤って秘密キーをコピーまたはアップロードしないように注意してください。

秘密キーを使用してコミットに署名することができ、これによりGitLabの使用とデータの安全性がさらに向上します。この署名は、公開キーを使用して誰でも検証できます。

詳細については、公開キー暗号としても知られる非対称暗号を参照してください。

前提要件

SSHを使用してGitLabと通信するには、以下が必要です:

  • GNU/Linux、macOS、およびWindows 10にプリインストールされているOpenSSHクライアント。
  • SSHバージョン6.5以降。それ以前のバージョンではMD5署名を使用していましたが、これは安全ではありません。

システムにインストールされているSSHのバージョンを確認するには、ssh -Vを実行します。

サポートされているSSHキーの種類

GitLabとの通信には、次のSSHキーの種類を使用できます:

管理者は、許可されるキーとその最小長を制限できます。

ED25519 SSHキー

Practical Cryptography With Go （実用的な暗号化とGo）の書籍では、ED25519キーはRSAキーよりも安全で高性能であることが示唆されています。

OpenSSH 6.5は2014年にED25519 SSHキーを導入するなど、ほとんどのオペレーティングシステムで利用可能になっています。

ED25519キーは、すべてのFIPSシステムで完全にサポートされていない可能性があります。詳細については、イシュー367429を参照してください。

ED25519_SK SSHキー

GitLabでED25519_SK SSHキーを使用するには、ローカルクライアントとGitLabサーバーにOpenSSH 8.2以降がインストールされている必要があります。

ECDSA_SK SSHキー

GitLabでECDSA_SK SSHキーを使用するには、ローカルクライアントとGitLabサーバーにOpenSSH 8.2以降がインストールされている必要があります。

RSA SSHキー

入手可能なドキュメントでは、ED25519がRSAよりも安全であることが示唆されています。

RSAキーを使用する場合、米国立標準技術研究所のPublication 800-57 Part 3 (PDF)は、少なくとも2048ビットのキーサイズを推奨しています。Goの制限により、RSAキーは8192ビットを超えることはできません。

デフォルトのキーサイズは、ssh-keygenのバージョンによって異なります。詳細については、インストールされているssh-keygenコマンドのmanページを確認してください。

既存のSSHキーペアの有無を確認する

キーペアを作成する前に、キーペアがすでに存在するかどうかを確認します。

  1. ホームディレクトリに移動します。
  2. .ssh/サブディレクトリに移動します。.ssh/サブディレクトリが存在しない場合は、ホームディレクトリにいないか、以前にsshを使用したことがないかのどちらかです。後者の場合は、SSHキーペアを生成する必要があります。
  3. 次のいずれかの形式のファイルが存在するかどうかを確認します:
    アルゴリズム公開キー秘密キー
    ED25519（推奨）id_ed25519.pubid_ed25519
    ED25519_SKid_ed25519_sk.pubid_ed25519_sk
    ECDSA_SKid_ecdsa_sk.pubid_ecdsa_sk
    RSA（少なくとも2048ビットのキーサイズ）id_rsa.pubid_rsa
    DSA（非推奨）id_dsa.pubid_dsa
    ECDSAid_ecdsa.pubid_ecdsa

SSHキーペアを生成する

既存のSSHキーペアがない場合は、新しいキーペアを生成します:

  1. ターミナルを開きます。

  2. 末尾にキーの種類とオプションのコメントを付けてssh-keygen -tを実行します。このコメントは、作成される.pubファイルに含まれています。コメントにメールアドレスを使用することもできます。

    例（ED25519の場合）:

    ssh-keygen -t ed25519 -C "<comment>"

    2048ビットRSAの場合:

    ssh-keygen -t rsa -b 2048 -C "<comment>"

  3. Enterキーを押します。次のような出力が表示されます:

    Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):

  4. デプロイキーを生成する場合、または他のキーを保存する特定のディレクトリに保存したい場合を除き、提案されたファイル名とディレクトリをそのまま使用します。

    SSHキーペアを特定のホスト専用にすることもできます。

  5. パスフレーズを指定します:

    Enter passphrase (empty for no passphrase):
Enter same passphrase again:

    ファイルの保存場所に関する情報を含む確認メッセージが表示されます。

公開キーと秘密キーが生成されます。GitLabアカウントに公開SSHキーを追加し、秘密キーを安全に保管してください。

別のディレクトリを指定するようにSSHを設定する

SSHキーペアをデフォルトディレクトリに保存しなかった場合は、秘密キーが保存されているディレクトリを指すようにSSHクライアントを設定します。

  1. ターミナルを開き、次のコマンドを実行します:

    eval $(ssh-agent -s)
ssh-add <directory to private SSH key>

  2. これらの設定を~/.ssh/configファイルに保存します。次に例を示します:

    # GitLab.com
Host gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/gitlab_com_rsa

# Private GitLab instance
Host gitlab.company.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/example_com_rsa

これらの設定の詳細については、SSH設定マニュアルのman ssh_configページを参照してください。

公開SSHキーはアカウントに紐付けられるため、GitLabに対して一意である必要があります。SSHを使用してコードをプッシュする際、SSHキーは唯一の識別子となります。SSHキーは単一のユーザーに一意にマップする必要があります。

GitLabアカウントにSSHキーを追加する

SSHをGitLabで使用するには、公開キーをGitLabアカウントにコピーします:

  1. 公開キーファイルの内容をコピーします。これは手動で行うことも、スクリプトを使用することもできます。

    これらの例では、id_ed25519.pubをファイル名に置き換えてください。たとえば、RSAの場合は、id_rsa.pubを使用します。

    tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy
    xclip -sel clip < ~/.ssh/id_ed25519.pub
    cat ~/.ssh/id_ed25519.pub | clip

  2. GitLabにサインインします。

  3. 左側のサイドバーで、自分のアバターを選択します。新しいナビゲーションをオンにしている場合、このボタンは右上隅にあります。

  4. プロファイルの編集を選択します。

  5. 左側のサイドバーでSSHキーを選択します。

  6. 新しいキーを追加を選択します。

  7. キーボックスに、公開キーの内容を貼り付けます。キーを手動でコピーする場合は、ssh-rsa、ssh-dss、ecdsa-sha2-nistp256、ecdsa-sha2-nistp384、ecdsa-sha2-nistp521、ssh-ed25519、sk-ecdsa-sha2-nistp256@openssh.com、またはsk-ssh-ed25519@openssh.comで始まり、コメントで終わる可能性があるキー全体をコピーしていることを確認してください。

  8. タイトルボックスに、Work LaptopやHome Workstationなどの説明を入力します。

  9. オプション。キーの使用タイプを選択します。Authentication（認証）またはSigning（署名）のいずれか、またはその両方で使用できます。Authentication & Signing（認証と署名）がデフォルト値です。

  10. オプション。有効期限を更新して、デフォルトの有効期限を変更します。詳細については、SSHキーの有効期限を参照してください。

  11. キーを追加を選択します。

接続できることを確認する

SSHキーが正しく追加されたことを確認します。

  1. 正しいサーバーに接続していることを確認するため、SSHホストキーのフィンガープリントを特定します。詳細は以下の説明を参照してください:

    • GitLab.comの場合は、SSHホストキーのフィンガープリントに関するドキュメントを参照してください。
    • GitLab Self-ManagedまたはGitLab Dedicatedの場合は、https://gitlab.example.com/help/instance_configuration#ssh-host-keys-fingerprintsを参照してください（gitlab.example.comはGitLabインスタンスのURLです）。

  2. ターミナルを開き、このコマンドを実行します。gitlab.example.comをGitLabのインスタンスURLに置き換えてください:

    ssh -T git@gitlab.example.com

    デフォルトでは、接続はgitユーザー名を使用しますが、管理者はユーザー名を変更できます。

  3. 最初の接続時に、GitLabホストの信頼性を確認する必要がある場合があります。次のようなメッセージが表示された場合は、画面の指示に従ってください:

    The authenticity of host 'gitlab.example.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)?

    歓迎メッセージが表示されます。

    Welcome to GitLab, <username>!

    メッセージが表示されない場合は、SSH接続の問題を解決する必要があるかもしれません。

SSHキーのパスフレーズを更新する

次の手順で、SSHキーのパスフレーズを更新できます:

  1. ターミナルを開き、次のコマンドを実行します:

    ssh-keygen -p -f /path/to/ssh_key

  2. プロンプトでパスフレーズを入力し、Enterキーを押します。

RSAキーペアをより安全な形式にアップグレードする

OpenSSHのバージョンが6.5 ～ 7.8の場合は、秘密RSA SSHキーをより安全なOpenSSH形式で保存できます。ターミナルを開いて次のコマンドを実行します:

ssh-keygen -o -f ~/.ssh/id_rsa

または、次のコマンドを実行して、より安全な暗号化形式で新しいRSAキーを生成することもできます:

ssh-keygen -o -t rsa -b 4096 -C "<comment>"

FIDO2ハードウェアセキュリティキー向けのSSHキーペアを生成する

ED25519_SKまたはECDSA_SK SSHキーを生成するには、OpenSSH 8.2以降を使用する必要があります:

  1. ハードウェアセキュリティキーをコンピューターに挿入します。

  2. ターミナルを開きます。

  3. 末尾にキーの種類とオプションのコメントを付けてssh-keygen -tを実行します。このコメントは、作成される.pubファイルに含まれています。コメントにメールアドレスを使用することもできます。

    たとえば、ED25519_SKの場合:

    ssh-keygen -t ed25519-sk -C "<comment>"

    ECDSA_SKの場合:

    ssh-keygen -t ecdsa-sk -C "<comment>"

    セキュリティキーがFIDO2レジデントキーをサポートしている場合は、SSHキーの作成時に有効にできます:

    ssh-keygen -t ed25519-sk -O resident -C "<comment>"

    -O residentは、キーをFIDO認証システム自体に保存する必要があることを示します。レジデントキーは、ssh-add -Kまたはssh-keygen -Kを使用してセキュリティキーから直接読み込むことができるため、新しいコンピューターへのインポートが簡単です。

  4. Enterキーを押します。次のような出力が表示されます:

    Generating public/private ed25519-sk key pair.
You may need to touch your authenticator to authorize key generation.

  5. ハードウェアセキュリティキーのボタンを押します。

  6. 提案されたファイル名とディレクトリをそのまま使用します:

    Enter file in which to save the key (/home/user/.ssh/id_ed25519_sk):

  7. パスフレーズを指定します:

    Enter passphrase (empty for no passphrase):
Enter same passphrase again:

    ファイルの保存場所に関する情報を含む確認メッセージが表示されます。

公開キーと秘密キーが生成されます。GitLabアカウントに公開SSHキーを追加します。

1PasswordでSSHキーペアを生成する

1Passwordと1Passwordブラウザ拡張機能を使用して、次のいずれかを行うことができます:

  • 新しいSSHキーを自動的に生成する。
  • 1Password Vaultにある既存のSSHキーを使用してGitLabで認証する。
  1. GitLabにサインインします。
  2. 左側のサイドバーで、自分のアバターを選択します。新しいナビゲーションをオンにしている場合、このボタンは右上隅にあります。
  3. プロファイルの編集を選択します。
  4. 左側のサイドバーでSSHキーを選択します。
  5. 新しいキーを追加を選択します。
  6. キーを選択すると、1Passwordヘルパーが表示されます。
  7. 1Passwordアイコンを選択し、1Passwordのロックを解除します。
  8. Create SSH Key（SSHキーの作成）を選択するか、既存のSSHキーを選択して公開キーを入力できます。
  9. タイトルボックスに、Work LaptopやHome Workstationなどの説明を入力します。
  10. オプション。キーの使用タイプを選択します。Authentication（認証）またはSigning（署名）のいずれか、またはその両方で使用できます。Authentication & Signing（認証と署名）がデフォルト値です。
  11. オプション。有効期限を更新して、デフォルトの有効期限を変更します。
  12. キーを追加を選択します。

1PasswordでSSHキーを使用する詳しい方法については、1Passwordドキュメントを参照してください。

リポジトリごとに異なるキーを使用する

リポジトリごとに異なるキーを使用できます。

ターミナルを開き、次のコマンドを実行します:

git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"

このコマンドはSSHエージェントを使用せず、Git 2.10以降が必要です。sshコマンドオプションの詳細については、sshとssh_configの両方のmanページを参照してください。

SSHキーを表示する

次の手順でアカウントのSSHキーを表示できます:

  1. 左側のサイドバーで、自分のアバターを選択します。新しいナビゲーションをオンにしている場合、このボタンは右上隅にあります。
  2. プロファイルの編集を選択します。
  3. 左側のサイドバーでSSHキーを選択します。

既存のSSHキーがページの下部に一覧表示されます。情報には次のものが含まれます:

  • キーのタイトル
  • 公開フィンガープリント
  • 許可されている使用タイプ
  • 作成日
  • 最終使用日
  • 有効期限

SSHキーを削除する

SSHキーを取り消すか削除して、アカウントから完全に削除できます。

SSHキーでコミットに署名している場合、SSHキーを削除すると、他の影響もあります。詳細については、削除されたSSHキーで署名されたコミットを参照してください。

SSHキーを取り消す

SSHキーのセキュリティが侵害された場合は、キーを取り消します。

前提要件:

  • SSHキーには、Signing（署名）またはAuthentication & Signing（認証と署名）の使用タイプが必要です。

次の手順でSSHキーを取り消せます:

  1. 左側のサイドバーで、自分のアバターを選択します。新しいナビゲーションをオンにしている場合、このボタンは右上隅にあります。
  2. プロファイルの編集を選択します。
  3. 左側のサイドバーでSSHキーを選択します。
  4. 取り消したいSSHキーの横にある取り消しを選択します。
  5. 取り消しを選択します。

SSHキーを削除する

次の手順でSSHキーを削除できます:

  1. 左側のサイドバーで、自分のアバターを選択します。新しいナビゲーションをオンにしている場合、このボタンは右上隅にあります。
  2. プロファイルの編集を選択します。
  3. 左側のサイドバーでSSHキーを選択します。
  4. 削除したいキーの横にある削除（ remove ）を選択します。
  5. 削除を選択します。

SSHキーの有効期限

SSHキーをアカウントに追加する際に、有効期限を設定できます。このオプションの設定は、セキュリティ漏洩のリスクを軽減するのに役立ちます。

SSHキーの有効期限が切れると、それを使用して認証またはコミットに署名することはできなくなります。新しいSSHキーを生成し、アカウントに追加する必要があります。

GitLab Self-ManagedおよびGitLab Dedicatedでは、管理者は有効期限を表示し、キーを削除する際のガイダンスとして使用できます。

GitLabは、有効期限が切れるSSHキーを毎日チェックし、通知を送信します:

  • 有効期限の7日前、UTC午前01:00。
  • 有効期限当日のUTC午前02:00。

単一のGitLabインスタンスで異なるアカウントを使用する

複数のアカウントを使用して、GitLabの単一インスタンスに接続できます。前のトピックで説明したコマンドを使用すると、これを行うことができます。ただし、IdentitiesOnlyをyesに設定しても、IdentityFileがHostブロックの外に存在する場合、サインインできません。

代わりに、~/.ssh/configファイルでホストにエイリアスを割り当てることができます。

  • Hostには、user_1.gitlab.comやuser_2.gitlab.comのようなエイリアスを使用します。高度な構成は維持が難しく、git remoteのようなツールを使用する場合、これらの文字列の方が理解しやすくなります。
  • IdentityFileには、秘密キーのパスを使用します。
# User1 Account Identity
Host <user_1.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key1>

# User2 Account Identity
Host <user_2.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key2>

user_1のリポジトリをクローンするには、git cloneコマンドでuser_1.gitlab.comを使用します:

git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git

originとしてエイリアスされている、以前にクローンしたリポジトリを更新するには、次のコマンドを使用します:

git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git

秘密キーと公開キーには機密データが含まれています。ファイルに対する権限を調節し、自分には読み取り可能でも他のユーザーにはアクセスできないように設定してください。

2FA（2要素認証）を設定する

SSH経由のGitに2要素認証（2FA）を設定できます。ED25519_SKまたはECDSA_SK SSHキーを使用する必要があります。

EclipseでEGitを使用する

EGitを使用している場合は、EclipseにSSHキーを追加できます。

Microsoft WindowsでSSHを使用する

Windows 10を実行している場合は、gitとsshの両方がプリインストールされているWSL 2を備えたLinux用Windowsサブシステム（WSL）を使用するか、Git for WindowsをインストールしてPowerShell経由でSSHを使用できます。

WSLで生成されたSSHキーは、Git for Windowsでは直接利用できません。その逆も同様です。これはホームディレクトリが異なるためです:

  • WSL: /home/<user>
  • Git for Windows: C:\Users\<user>

.ssh/ディレクトリをコピーして同じキーを使用するか、各環境でキーを生成します。

Windows 11を実行していて、OpenSSH for Windowsを使用している場合は、HOME環境変数が正しく設定されていることを確認してください。正しく設定されていない場合、秘密SSHキーが見つからない可能性があります。

代替ツールは次のとおりです:

エンタープライズのユーザーに対するSSHキーの無効化

この機能の利用可否は、機能フラグによって制御されます。詳細については、履歴を参照してください。

前提要件:

  • Enterpriseユーザーが所属するグループのオーナーロールを持っている必要があります。

グループのエンタープライズのユーザーのSSHキーを無効にすると:

  • エンタープライズのユーザーが新しいSSHキーを追加できなくなります。この動作は、エンタープライズユーザーがグループ管理者である場合でも適用されます。
  • エンタープライズのユーザーの既存のSSHキーを無効にします。

エンタープライズのユーザーに対するSSHキーを無効にしても、サービスアカウントのデプロイメントキーは無効になりません。

エンタープライズのユーザーのSSHキーを無効にするには:

  1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
  2. 設定 > 一般を選択します。
  3. 権限とグループ機能を展開します。
  4. エンタープライズのユーザーで、SSHキーを無効にするを選択します。
  5. 変更を保存を選択します。

エンタープライズユーザーアカウントを削除またはブロックすると、そのユーザーのパーソナルSSHキーは自動的に失効します。

GitLabサーバー上のSSH設定をオーバーライドする

GitLabはシステムにインストールされたSSHデーモンと統合し、すべてのアクセス要求が処理されるユーザー（通常はgitという名前）を指定します。SSH経由でGitLabサーバーに接続するユーザーは、ユーザー名ではなくSSHキーによって識別されます。

GitLabサーバーで実行されるSSHクライアント操作は、このユーザーとして実行されます。このSSH設定は変更できます。たとえば、認証リクエストに使用する秘密SSHキーをこのユーザーに指定できます。ただし、この方法はnot supported（サポートされていません）。重大なセキュリティリスクがあるため、きわめて非推奨とされています。

GitLabはこの状態をチェックし、サーバーがこの方法で設定されている場合は、このセクションに誘導します。次に例を示します:

$ gitlab-rake gitlab:check

Git user has default SSH configuration? ... no
  Try fixing it:
  mkdir ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
  For more information see:
  doc/user/ssh.md#overriding-ssh-settings-on-the-gitlab-server
  Please fix the error above and rerun the checks.

できるだけ早くカスタム設定を削除してください。これらのカスタマイズはexplicitly not supported（明示的にサポートされていません）。予告なく動作しなくなる可能性があります。

GitLab SSHの所有権と権限を確認する

GitLab SSHフォルダーとファイルには、次の権限が必要です:

  • /var/opt/gitlab/.ssh/フォルダーは、gitグループとgitユーザーが所有し、権限は700に設定されている必要があります。
  • authorized_keysファイルの権限は600に設定されている必要があります。
  • authorized_keys.lockファイルの権限は644に設定されている必要があります。

これらの権限が正しいことを確認するには、次のスクリプトを実行します:

stat -c "%a %n" /var/opt/gitlab/.ssh/.

権限を設定する

権限が間違っている場合は、アプリケーションサーバーにサインインして次を実行します:

cd /var/opt/gitlab/
chown git:git /var/opt/gitlab/.ssh/
chmod 700  /var/opt/gitlab/.ssh/
chmod 600  /var/opt/gitlab/.ssh/authorized_keys
chmod 644  /var/opt/gitlab/.ssh/authorized_keys.lock