# Dependabot × プライベートレジストリ認証 完全ガイド：npm/Docker/Maven/PyPI・CodeArtifact・OIDC・self-hosted ランナー > 社内・プライベートレジストリの依存を Dependabot で更新するための実装ガイド。公式ドキュメント（2026年6月時点）に忠実に、registries ブロックの全 type 別認証フィールド、Dependabot シークレット（≠Actions シークレット）、GitHub Packages の自動認証、AWS CodeArtifact・Google Artifact Registry・JFrog Artifactory の OIDC、ECR の静的AWS認証、そして私設ネットワークに到達する self-hosted ランナー（dependabot ラベル）までを、コピペできる実コードと最小権限設計で解説します。 - Published: 2026-06-28 - Author: 友田 陽大 - Tags: Dependabot, サプライチェーンセキュリティ, GitHub Actions, DevSecOps, 依存関係管理, セキュリティ - URL: https://tomodahinata.com/fr/blog/dependabot-private-registries-authentication-self-hosted-runners-guide - Category: Dependabot & dependency automation - Pillar guide: https://tomodahinata.com/fr/blog/dependabot-production-guide ## Key points - プライベートレジストリ対応には2つの壁がある——『認証（credentials）』と『到達性（network）』。前者は registries ブロック＋Dependabot シークレット、後者は self-hosted ランナーで越える - registries の認証情報は ${{secrets.NAME}} で渡すが、参照先は Dependabot 専用シークレットストア（Settings→Secrets and variables→Dependabot）。通常の Actions シークレットとは別で、Dependabot ジョブからは Actions シークレットは見えない - type は npm-registry / docker-registry / maven-repository / python-index / nuget-feed / rubygems-server / composer-repository / cargo-registry / terraform-registry / git / helm-registry / hex-* / goproxy-server / pub-repository。多くが username/password か token、一部は replaces-base に対応 - GitHub Packages / Container Registry は特別で、registries エントリ不要。Dependabot が GITHUB_TOKEN で自動認証する。CodeArtifact / Azure Artifacts / Cloudsmith / Google Artifact Registry / JFrog Artifactory は OIDC に対応し、静的トークンを避けられる - GitHub-hosted ランナーから到達できない私設網のレジストリは self-hosted ランナーで更新する。runner に dependabot ラベルが無いとジョブが無限にキューされる。ランナーは隔離し最小権限で運用する --- 「公開パッケージは Dependabot で自動更新できた。けれど**社内 npm レジストリや Artifactory、ECR のプライベートイメージ**は更新されない」——エンタープライズで必ずぶつかる壁です。原因は2つに分解できます。**認証（credentials）が通らない**のか、**ネットワーク到達性（network）が無い**のか。この2つは対処がまったく違います。 この記事は[Dependabot 本番運用ガイド](/blog/dependabot-production-guide)の各論として、**プライベートレジストリ対応**を実装レベルで網羅します。型別の認証から OIDC、self-hosted ランナーまで、**そのまま使える設定**で解説します。 > **この記事のルール**：`registries` の type・認証フィールド・OIDC 対応は **GitHub 公式ドキュメント（2026年6月時点）** に基づきます。認証情報は**絶対にリポジトリにハードコードせず**、Dependabot シークレットで渡してください。本番前に必ず[公式のプライベートレジストリ設定](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot)で最新を確認してください。 --- ## 0. 2つの壁：認証と到達性 | 壁 | エラーコード（公式） | 越え方 | | --- | --- | --- | | **認証** | `private_source_authentication_failure` | `registries` ブロック ＋ **Dependabot シークレット** | | **認証（証明書）** | `private_source_certificate_failure` | 社内CA・自己署名証明書を**信頼させる**（実運用は CA を投入できる **self-hosted ランナー**） | | **到達性** | `private_source_not_reachable` | **self-hosted ランナー**（私設網にランナーを置く） | | **到達性（タイムアウト）** | `private_source_timed_out` | **ネットワーク経路・プロキシ許可リスト**を確認。私設網なら **self-hosted ランナー** | > **まず症状で切り分ける**：レジストリの管理画面や Dependabot のジョブログに出る**エラーコードで壁の種類が特定できます**。`authentication` / `certificate` は「認証の壁」、`not_reachable` / `timed_out` は「到達性の壁」。エラーコードの全分類は[トラブルシューティングガイド](/blog/dependabot-troubleshooting-not-creating-pull-requests-errors-guide)を参照。 クラウドのマネージドレジストリ（CodeArtifact, Artifact Registry, Artifactory SaaS）は**公開エンドポイント＋認証**なので「認証の壁」だけ。**VPC 内などインターネットから到達できない**レジストリは「到達性の壁」も越える必要があります。まず自分がどちらかを見極めます。 --- ## 1. registries ブロックの基本 `dependabot.yml` のトップレベルに `registries` を定義し、`updates` の各ジョブから紐づけます。 ```yaml 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` ごとに使える認証フィールドが決まっています（公式）。よく使うものを表にまとめます。 | `type` | 主な認証フィールド | replaces-base | 備考 | | --- | --- | --- | --- | | `npm-registry` | `username`/`password` または `token` | ✓ | npm/yarn/pnpm | | `docker-registry` | `username`/`password`、または ECR 用の静的AWS認証 | ✓ | コンテナイメージ | | `maven-repository` | `username`/`password`、または OIDC（`tenant-id`/`client-id`） | ✓ | Maven/Gradle | | `python-index` | `username`/`password`、`token`、または OIDC | ✓ | pip/uv/poetry | | `nuget-feed` | `username`/`password`、`token`、または OIDC | ✗ | .NET | | `rubygems-server` | `username`/`password` または `token` | ✓ | Bundler | | `composer-repository` | `username`/`password` | — | PHP（GitHub PAT 可） | | `cargo-registry` | `token`（任意で `registry`） | — | Rust | | `terraform-registry` | `token` | — | Terraform | | `git` | `username`/`password` | — | Git 由来の依存 | | `helm-registry` | `username`/`password` | — | **HTTP Basic 認証のみ**・OCI 非対応 | | `hex-organization` | `organization`/`key` | — | Elixir | | `hex-repository` | `repo`/`url`/`auth-key`（任意で `public-key-fingerprint`） | — | Elixir 自前リポジトリ | | `goproxy-server` | `username`/`password` | — | Go モジュールプロキシ | | `pub-repository` | `url`/`token` | — | Dart/Flutter | > `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） ```yaml 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認証） ```yaml 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 に限定でき、書き込み権限は不要です。 ```json { "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 ベースイメージ更新ガイド](/blog/dependabot-docker-base-image-digest-pinning-updates-guide)へ。 ### 5.3 JFrog Artifactory（npm 例） ```yaml 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` ジョブが使うレジストリだけを明示的に紐づけます**。 ```yaml 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章](#3-github-packages-は特別扱いregistries-不要)）。 --- ## 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分類のエラーコード](/blog/dependabot-troubleshooting-not-creating-pull-requests-errors-guide#4-プライベートレジストリのエラー4分類)で切り分け この設定を CI/CD 全体の依存関係自動化に広げる設計は[Dependabot 本番運用ガイド](/blog/dependabot-production-guide)を、認証・到達性以外のエラーは[トラブルシューティングガイド](/blog/dependabot-troubleshooting-not-creating-pull-requests-errors-guide)を参照してください。