【Jenkins】「Could not find credentials」の究極解決ガイド【現場のプロが徹底解説】

JenkinsでCI/CDパイプラインを運用していると、ビルド時に「Could not find credentials」というエラーに遭遇することがあります。このエラーは、多くの場合、Jenkinsがジョブの実行に必要な認証情報（SSHキー、ユーザー名/パスワード、APIトークンなど）を見つけられない、またはアクセスできないことを意味します。

この記事では、15年以上の経験を持つシニアITエンジニアが、このエラーを迅速に解決するための具体的な手順から、エラーの真の原因、そして再発防止のためのシステム設計・運用アドバイスまで、現場で培った実践的な知見を網羅的に解説します。単なるマニュアルの羅列ではない、「プロの視点」からトラブルシューティングのヒントを得てください。

結論：最も速く解決する方法

このエラーの最も一般的な原因は、必要なCredentialsがJenkinsに登録されていないか、正しく参照されていないことです。以下の手順でCredentialsを登録・確認し、ビルドを再実行してください。

  1. Jenkinsダッシュボードへアクセス:JenkinsのWebインターフェースに管理者権限を持つユーザーでログインします。
  2. Credentials管理画面へ移動:左側のメニューから「Jenkinsの管理」をクリックし、次に「Credentials」を選択します。
    • ヒント: 「Credentials」の画面では、「Stores scoped to Jenkins」の下にある「システム」→「Global credentials (unrestricted)」を選択することが多いです。これは、Jenkinsインスタンス全体で利用可能なCredentialsを管理する場所です。特定のジョブやフォルダーに限定したい場合は、そのスコープを選択してください。
  3. 新しいCredentialsの追加:「Global credentials (unrestricted)」ページで「Add Credentials」ボタンをクリックします。
  4. Credentialsの種類を選択:「Kind」ドロップダウンメニューから、使用するCredentialsの種類を選択します。例えば：
    • SSHキーを使用する場合: SSH Username with private key
    • ユーザー名とパスワードを使用する場合: Username with password
    • APIトークンなどを使用する場合: Secret text または Secret file
  5. 必要な情報を入力:選択したKindに応じて、必要な情報を入力します。特に重要なのは以下の項目です。
    • ID (必須): これは、Jenkinsパイプラインやジョブ設定でCredentialsを参照する際に使用する一意の識別子です。エラーメッセージで示されているIDと完全に一致させる必要があります。
    • Description: 何のためのCredentialsか、誰がいつ作成したかなどを記述しておくと、後々の管理が楽になります。
    • Username, Private Key, Passphrase, Password など、選択したKindに合わせた詳細情報。
    SSH Private Keyの登録に関する注意:

    • 「Enter directly」を選択し、SSHの秘密鍵（例: id_rsaファイルの内容）を直接ペーストします。公開鍵ではありません。
    • パスフレーズが設定されている場合は、忘れずに「Passphrase」欄に入力してください。
  6. Credentialsの保存:入力が完了したら「OK」ボタンをクリックしてCredentialsを保存します。
  7. ジョブ設定の更新とビルドの再実行:Credentialsを登録したら、Jenkinsパイプライン（Jenkinsfile）やフリースタイルジョブの設定を確認し、登録したCredentialsのIDが正しく参照されているかを確認します。
    • Pipelineの場合: withCredentialsステップ内で、登録したCredentials IDを指定します。 
      pipeline {
    agent any
    stages {
        stage('Deploy') {
            steps {
                withCredentials([sshUserPrivateKey(credentialsId: 'your-ssh-key-id', keyFileVariable: 'SSH_KEY_FILE', usernameVariable: 'SSH_USERNAME')]) {
                    sh "ssh -i \${SSH_KEY_FILE} \${SSH_USERNAME}@your-server 'ls -la'"
                }
            }
        }
    }
}
    • フリースタイルジョブの場合: ビルドステップでCredentialsを利用するプラグイン（例: Gitプラグイン）の設定で、登録したCredentialsを選択します。

    設定を保存し、ビルドを再実行してエラーが解消されたか確認します。

【プロの視点】このエラーの真の原因と緊急度

「Could not find credentials」というメッセージはシンプルですが、その背後にはいくつかの真の原因が潜んでいます。現場では、見かけ上のエラーメッセージに惑わされず、その本質を見抜くことが重要です。

真の原因：JenkinsのCredentials解決パスの不一致

このエラーは、Jenkinsがビルド実行時に特定の認証情報を要求された際、内部のCredentialsプロバイダが、要求されたIDに対応する認証情報を見つけられない状態を指します。具体的には以下のいずれかが原因です。

  • IDの不一致またはスペルミス: 最も単純で最も頻繁に発生します。パイプラインスクリプトやジョブ設定で指定されたCredentials IDと、Jenkinsに登録されているCredentials IDが1文字でも異なると、Jenkinsは「見つけられない」と判断します。
  • スコープの誤り: JenkinsのCredentialsには、グローバル、ドメイン、フォルダー、ジョブといったスコープがあります。特定のスコープで登録されたCredentialsは、そのスコープ外からは参照できません。例えば、Globalで登録すべきCredentialsを、特定のフォルダー内に限定して登録してしまった場合などです。
  • Credentials種類の誤解: 例えば、SSH秘密鍵を登録するべき箇所に、誤って「Username with password」タイプで別の情報を登録している場合。JenkinsはIDは見つけるかもしれませんが、それが期待するタイプのCredentialsではないため利用できず、「見つけられない」と報告することがあります。
  • 権限不足: Jenkinsエージェントが、特定のCredentialsファイル（例: SSHキーファイルを手動で配置した場合）にアクセスするOSレベルの権限を持っていない場合。これは稀なケースですが、発生し得ます。
  • プラグインの問題/キャッシュ: ごく稀に、Credentials関連のJenkinsプラグインの不具合や、JenkinsがCredentials情報を適切にキャッシュできていないことが原因で発生することもあります。その場合はJenkinsの再起動が有効な場合があります。

現場でよくある見落としポイント

  • IDのコピペミス: 手入力は厳禁。IDは必ずコピー＆ペーストで設定しましょう。特にハイフンやアンダースコアなどの記号は見間違いやすいです。
  • Pipelineスクリプト内での変数展開: withCredentialsステップでcredentialsId: 'some-id'と直接指定するべきところを、誤ってcredentialsId: "${MY_CREDENTIAL_ID}"のような環境変数で指定し、その環境変数が適切に設定されていない、というケース。
  • SSH Private Keyの形式: 登録するSSH秘密鍵がPEM形式であるか、または-----BEGIN OPENSSH PRIVATE KEY-----のようなヘッダーとフッターが含まれているかを確認します。PuTTYgenで生成された鍵の場合、PEM形式に変換する必要があります。
  • パスフレーズの有無: SSH秘密鍵にパスフレーズが設定されているにも関わらず、JenkinsのCredentials登録時にパスフレーズを入力し忘れる、または間違える。
  • エージェント上のCredential利用: Jenkinsマスターから直接ではない、特定のビルドエージェントでCredentialsを使用する際に、そのエージェントが該当のCredentialsにアクセスできるか（特に物理ファイルの場合）。

このエラーの緊急度

「Could not find credentials」エラーは、ビルドの失敗に直結するため、緊急度は「高」と判断されます。CI/CDパイプラインが停止し、アプリケーションのデプロイやテストが滞るため、迅速な対応が求められます。特に本番環境へのデプロイパイプラインで発生した場合、ビジネスへの影響は甚大です。

注意: このエラーは通常、セキュリティ上の問題を示すものではありません（認証情報が漏洩した、などの兆候ではない）。むしろ、認証情報が適切に提供されていないという運用上の問題です。しかし、解決が遅れるとデリバリープロセスが停止するため、即座に対応すべきです。

再発防止のためのシステム設計・運用アドバイス

一度解決しても、また同じエラーに悩まされないために、シニアエンジニアとして以下のシステム設計・運用プラクティスを推奨します。

  1. Credentialの命名規則を徹底する一貫性のある明確な命名規則（例: [プロジェクト名]-[サービス名]-[タイプ]）を策定し、チーム全体で共有します。これにより、必要なCredentialsを検索しやすくなり、誤って異なるCredentialsを参照するリスクを減らせます。
    • 例: myproject-dev-ssh-deploy, myproject-prod-api-token
  2. スコープを最適化し、不必要なGlobal Credentialsを避けるCredentialsは、必要最低限のスコープ（例: 特定のフォルダーやジョブ）で登録することを検討してください。GlobalスコープのCredentialsは便利ですが、誤用やセキュリティリスクの原因となることがあります。Jenkinsのフォルダー機能を活用し、プロジェクトごとにCredentialsを分離することが有効です。
  3. Jenkins Shared Librariesを活用するJenkins Pipelineを使用している場合、Credentialsの参照ロジックをShared Librariesに集約することで、Jenkinsfileの記述をシンプルにし、Credential IDのハードコーディングを避けることができます。 
    // vars/credentialUtils.groovy (in your shared library)
def withProjectSshKey(closure) {
    withCredentials([sshUserPrivateKey(credentialsId: 'myproject-dev-ssh-key', keyFileVariable: 'SSH_KEY_FILE', usernameVariable: 'SSH_USERNAME')]) {
        closure.call()
    }
}

// Jenkinsfile
@Library('my-shared-library') _
pipeline {
    agent any
    stages {
        stage('Deploy') {
            steps {
                script {
                    credentialUtils.withProjectSshKey {
                        sh "ssh -i \${SSH_KEY_FILE} \${SSH_USERNAME}@target-server 'deploy-script.sh'"
                    }
                }
            }
        }
    }
}

    これにより、Credential IDが変更された場合でも、Shared Libraryのコードを一度修正するだけで済み、複数のJenkinsfileを修正する手間が省けます。

  4. 外部シークレット管理システムとの連携を検討する大規模な環境や高度なセキュリティが求められる場合、HashiCorp Vault、AWS Secrets Manager、Azure Key Vaultなどの外部シークレット管理システムとJenkinsを連携させることを強く推奨します。これにより、CredentialsをJenkins内部に直接保存することなく、安全かつ一元的に管理できます。
    • Jenkinsにはこれらの外部システムと連携するためのプラグインが用意されています。
  5. 定期的なCredentialsの棚卸しと更新使用されていないCredentialsを定期的に削除し、パスワードやSSHキーを定期的に更新するポリシーを確立します。これにより、セキュリティを維持し、管理画面の cluttered 化を防ぎます。
  6. 最小権限の原則を適用するCredentialsに付与する権限は、そのCredentialsで実行される操作に必要最低限のものに絞ります。例えば、デプロイ用のSSHキーであれば、デプロイ先のサーバーでのみ機能するような制限を設けるなどです。

これらのプラクティスを導入することで、JenkinsのCredential管理はより堅牢になり、「Could not find credentials」のようなエラーに遭遇する頻度を大幅に減らすことができるでしょう。安定したCI/CDパイプラインの実現には、このような基盤作りが不可欠です。

“`

Related Posts