# 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 ラベル）までを、コピペできる実コードと最小権限設計で解説します。

- 公開日: 2026-06-28
- 著者: 友田 陽大
- タグ: Dependabot, サプライチェーンセキュリティ, GitHub Actions, DevSecOps, 依存関係管理, セキュリティ
- URL: https://tomodahinata.com/blog/dependabot-private-registries-authentication-self-hosted-runners-guide
- カテゴリ: Dependabot・依存関係の自動更新
- 総合ガイド: https://tomodahinata.com/blog/dependabot-production-guide

## 要点

- プライベートレジストリ対応には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_not_reachable` / `timed_out` | **self-hosted ランナー**（私設網にランナーを置く） |

クラウドのマネージドレジストリ（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 を推奨）。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. 到達性の壁：self-hosted ランナー

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

### 6.1 必要になる場面

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

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

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

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

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

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

---

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

- [ ] 認証情報は**すべて 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分類)で切り分け

---

## 8. FAQ

**Q. registries の token はどこに置きますか？**
A. **Dependabot シークレット**（Settings → Secrets and variables → Dependabot）です。Actions シークレットとは別ストアで、Dependabot ジョブからは Actions シークレットは参照できません。

**Q. GitHub Packages の内部パッケージにも registries 定義が要りますか？**
A. 不要です。Dependabot が `GITHUB_TOKEN` で自動認証します。アクセスは「Manage Actions access」で管理します。

**Q. 静的トークンを置きたくありません。**
A. OIDC 対応レジストリ（CodeArtifact / Azure Artifacts / Cloudsmith / Google Artifact Registry / JFrog Artifactory）なら OIDC 連携で長期シークレットを保管せずに済みます。

**Q. 設定したのに `private_source_not_reachable` になります。**
A. 認証ではなく**到達性**の問題です。私設網のレジストリなら **self-hosted ランナー**を立て、ランナーに `dependabot` ラベルを付けてください（ラベルが無いとジョブが無限キューになります）。

**Q. self-hosted ランナーは普段の CI ランナーと共有してよい？**
A. 推奨しません。Dependabot 用は**隔離・最小権限**で運用し、本番機密に触れられない環境にしてください。