Dependabot × プライベートレジストリ認証 完全ガイド：npm/Docker/Maven/PyPI・CodeArtifact・OIDC・self-hosted ランナー

「公開パッケージは Dependabot で自動更新できた。けれど社内 npm レジストリや Artifactory、ECR のプライベートイメージは更新されない」——エンタープライズで必ずぶつかる壁です。原因は2つに分解できます。認証（credentials）が通らないのか、ネットワーク到達性（network）が無いのか。この2つは対処がまったく違います。

この記事はDependabot 本番運用ガイドの各論として、プライベートレジストリ対応を実装レベルで網羅します。型別の認証から OIDC、self-hosted ランナーまで、そのまま使える設定で解説します。

この記事のルール：registries の type・認証フィールド・OIDC 対応は GitHub 公式ドキュメント（2026年6月時点） に基づきます。認証情報は絶対にリポジトリにハードコードせず、Dependabot シークレットで渡してください。本番前に必ず公式のプライベートレジストリ設定で最新を確認してください。

0. 2つの壁：認証と到達性

まず症状で切り分ける：レジストリの管理画面や Dependabot のジョブログに出るエラーコードで壁の種類が特定できます。authentication / certificate は「認証の壁」、not_reachable / timed_out は「到達性の壁」。エラーコードの全分類はトラブルシューティングガイドを参照。

クラウドのマネージドレジストリ（CodeArtifact, Artifact Registry, Artifactory SaaS）は公開エンドポイント＋認証なので「認証の壁」だけ。VPC 内などインターネットから到達できないレジストリは「到達性の壁」も越える必要があります。まず自分がどちらかを見極めます。

1. registries ブロックの基本

dependabot.yml のトップレベルに registries を定義し、updates の各ジョブから紐づけます。

version: 2
registries:
  my-npm:
    type: npm-registry
    url: https://npm.example.com
    token: ${{secrets.DEPENDABOT_NPM_TOKEN}}   # ← Dependabot シークレットを参照

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    registries:
      - my-npm        # このジョブで使うレジストリ

最重要：${{secrets.NAME}} が参照するのは Dependabot 専用のシークレットストアです。場所は Settings → Secrets and variables → Dependabot（リポジトリまたは Organization）。通常の Actions シークレットとは別物で、Dependabot のジョブからは Actions シークレットは見えません。これは「侵害された依存が、CI 経由で秘密情報を盗み出す」のを防ぐ設計です。シークレットは GitHub に届く前に暗号化され、Dependabot が使う瞬間まで暗号化されたままです。

2. type 別 認証リファレンス

type ごとに使える認証フィールドが決まっています（公式）。よく使うものを表にまとめます。

replaces-base: true は、「公開レジストリ（例：registry.npmjs.org）の代わりにこの private レジストリを既定として使う」指定です。社内ミラーを唯一の取得元にしたいときに使います。

3. GitHub Packages は“特別扱い”（registries 不要）

GitHub Packages / GitHub Container Registry（ghcr.io）は、registries エントリを書く必要がありません。

公式：「Dependabot は GITHUB_TOKEN で自動的に認証できる。これは GitHub Actions ワークフローが使うのと同じ『Manage Actions access』の付与を利用する。PAT や dependabot.yml の registry エントリは不要」。

つまり、同じ Organization の GitHub Packages に置いた内部パッケージは、追加設定ゼロで更新対象になります。アクセス権はリポジトリの「Manage Actions access」で管理します。これは GitHub エコシステムに寄せる最大のメリットの一つです。

4. OIDC で“静的トークンを置かない”

静的なトークン/パスワードは、失効管理・漏洩リスク・棚卸しの手間がつきまといます。OIDC（OpenID Connect）対応のレジストリなら、短命の連携トークンで認証でき、長期シークレットを保管しない設計にできます。

公式が OIDC 対応を挙げているのは次のとおりです。

• AWS CodeArtifact
• Azure DevOps Artifacts
• Cloudsmith
• Google Cloud Artifact Registry
• JFrog Artifactory

maven-repository / python-index / nuget-feed などで tenant-id / client-id を使う形が該当します。セキュリティとコスト効率（鍵管理の運用負荷削減）の両面で、可能なら OIDC を第一選択にしてください。鍵レス CI/CD と同じ思想です。

5. クラウド別の実例

5.1 AWS CodeArtifact（npm / pip）

version: 2
registries:
  codeartifact-npm:
    type: npm-registry
    url: https://my-domain-111122223333.d.codeartifact.ap-northeast-1.amazonaws.com/npm/my-repo/
    token: ${{secrets.DEPENDABOT_CODEARTIFACT_TOKEN}}
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    registries: ["codeartifact-npm"]

CodeArtifact はOIDC にも対応しているため、可能なら静的トークンではなく OIDC 連携に寄せます。

5.2 Amazon ECR（Docker・静的AWS認証）

registries:
  ecr:
    type: docker-registry
    url: 111122223333.dkr.ecr.ap-northeast-1.amazonaws.com
    username: ${{secrets.DEPENDABOT_AWS_ACCESS_KEY_ID}}
    password: ${{secrets.DEPENDABOT_AWS_SECRET_ACCESS_KEY}}

docker-registry はECR からのプルに静的 AWS 認証を使えます。付与する IAM は読み取り専用の最小権限に絞ります。プル系アクションは対象リポジトリの ARN に限定でき、書き込み権限は不要です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DependabotEcrGetToken",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "DependabotEcrPullReadOnly",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:ListImages"
      ],
      "Resource": "arn:aws:ecr:ap-northeast-1:111122223333:repository/my-app"
    }
  ]
}

ecr:GetAuthorizationToken はアカウント単位の権限で Resource を絞れず * が必須ですが、実際にイメージを取得するプル系アクションは対象リポジトリの ARN に限定できます。IAM ユーザーのアクセスキーを長期保管したくない場合は、OIDC でロールを引き受ける構成を検討してください。

Docker ベースイメージ更新の運用はDocker ベースイメージ更新ガイドへ。

5.3 JFrog Artifactory（npm 例）

registries:
  artifactory-npm:
    type: npm-registry
    url: https://artifactory.example.com/artifactory/api/npm/npm-virtual
    username: ${{secrets.DEPENDABOT_ARTIFACTORY_USER}}
    password: ${{secrets.DEPENDABOT_ARTIFACTORY_TOKEN}}
    replaces-base: true

Artifactory もOIDC 対応。ガバナンス要件が厳しい組織ほど OIDC を選ぶ価値があります。

6. コピペで動く「全部入り」dependabot.yml

複数のプライベートレジストリを1ファイルで扱う実務パターンです。registries をトップレベルに定義し、各 updates ジョブが使うレジストリだけを明示的に紐づけます。

version: 2

registries:
  # ① AWS CodeArtifact（npm）— 可能なら静的トークンではなく OIDC 連携へ寄せる
  codeartifact-npm:
    type: npm-registry
    url: https://my-domain-111122223333.d.codeartifact.ap-northeast-1.amazonaws.com/npm/my-repo/
    token: ${{secrets.DEPENDABOT_CODEARTIFACT_TOKEN}}
  # ② Amazon ECR（Docker）— 読み取り専用IAMの静的AWS認証
  ecr:
    type: docker-registry
    url: 111122223333.dkr.ecr.ap-northeast-1.amazonaws.com
    username: ${{secrets.DEPENDABOT_AWS_ACCESS_KEY_ID}}
    password: ${{secrets.DEPENDABOT_AWS_SECRET_ACCESS_KEY}}
  # ③ JFrog Artifactory（Maven）— 社内ミラーを唯一の取得元に
  artifactory-maven:
    type: maven-repository
    url: https://artifactory.example.com/artifactory/libs-release
    username: ${{secrets.DEPENDABOT_ARTIFACTORY_USER}}
    password: ${{secrets.DEPENDABOT_ARTIFACTORY_TOKEN}}
    replaces-base: true
  # ④ 社内プライベート PyPI（pip）
  internal-pypi:
    type: python-index
    url: https://pypi.example.com/simple
    token: ${{secrets.DEPENDABOT_PYPI_TOKEN}}

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    registries:
      - codeartifact-npm      # このジョブは CodeArtifact だけを参照

  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
    registries:
      - ecr

  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
    registries:
      - artifactory-maven

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    registries:
      - internal-pypi

  # GitHub Packages はここに書かない（GITHUB_TOKEN で自動認証）
  - package-ecosystem: "npm"
    directory: "/packages/internal"
    schedule:
      interval: "weekly"

最小権限の要点：各 updates ジョブは、既定ではどの registries にもアクセスできません。ジョブ側の registries: に列挙したものだけが使えます。npm ジョブから ECR 認証情報は見えないので、認証情報の露出面を最小化できます。GitHub Packages のジョブには registries を書かない——GITHUB_TOKEN で自動認証されるからです（3章）。

7. 到達性の壁：self-hosted ランナー

ここまでは「認証」の話。VPC 内・社内ネットワークのみで到達できるレジストリは、GitHub-hosted ランナーからはそもそも届きません。このとき self-hosted ランナーで Dependabot を走らせます。

7.1 必要になる場面

• インターネット非公開の社内 Artifactory / Nexus / プライベート PyPI / 社内 Go プロキシ
• VPC エンドポイント経由でしか到達できない CodeArtifact / Artifact Registry

7.2 セットアップの要点（公式）

1. 前提：Dependabot が有効・GitHub Actions が有効。
2. ランナーを用意：リポジトリまたは Organization レベルで self-hosted ランナーを登録。
3. 環境要件を満たす：Dependabot ジョブが動く実行環境（必要なツール・ネットワーク）。
4. dependabot ラベルを付与：単一リポジトリなら dependabot ラベルを、Organization なら所定のラベルを付ける。

ハマりどころ（必読）：この機能を有効にすると、Dependabot ジョブは dependabot ラベルを持つランナーでしか実行されません。ラベルを付け忘れると、ジョブはいつまでもキューされ続ける（＝何も起きないように見える）重大な落とし穴です。有効化前に「ラベル付きランナーが本当に存在するか」を必ず検証してください。

7.3 ネットワークとセキュリティ設計

• ネットワーク：ランナーから GitHub と対象レジストリの両方に到達できること。Firewall/プロキシの許可リストを整える。
• 隔離：self-hosted ランナーは、Dependabot が信頼境界の外（更新後の依存）に触れ得る実行環境です。他用途と共有せず隔離し、最小権限で運用する（ネットワークも認証情報も）。本番の機密に触れられる場所で動かさない。

8. セキュリティ・チェックリスト

• 認証情報はすべて Dependabot シークレット（Actions シークレットに置かない・ハードコードしない）
• 可能なレジストリは OIDC（CodeArtifact / Azure Artifacts / Cloudsmith / Artifact Registry / Artifactory）で静的トークンを排除
• トークンは最小権限・読み取り専用（更新の取得に必要な範囲だけ）
• GitHub Packages は GITHUB_TOKEN 自動認証を活用し、余計な PAT を作らない
• self-hosted ランナーは隔離・最小権限、dependabot ラベルを検証
• 認証エラー時は4分類のエラーコードで切り分け

この設定を CI/CD 全体の依存関係自動化に広げる設計はDependabot 本番運用ガイドを、認証・到達性以外のエラーはトラブルシューティングガイドを参照してください。