npmのbypass-2FA GATが失敗する原因と対処法｜OIDC・Staged Publishing移行手順

2026年7月31日以降、これまでnpmのbypass-2FA付きGranular Access Token（GAT）で動いていた自動化が、トークン管理やメンテナー追加、パッケージ権限変更などで突然失敗する場合があります。

原因はトークンの期限切れではなく、npmが機密性の高い管理操作を対話型2FA必須に変更したためです。bypass-2FAを有効にしたGATであっても、これらの操作をCI/CDから実行できなくなりました。

対処方法は、管理操作をWebまたはCLIから対話的に行い、自動公開はTrusted Publishing（OIDC）へ移行することです。公開前に人の確認を挟みたい場合は、Staged Publishingを利用します。なお、bypass-2FA GATによる直接のnpm publishは現時点では利用できますが、2027年1月を目標に廃止される予定です。(The GitHub Blog)

npmのbypass-2FA GATによる自動化が失敗する原因

npmのGranular Access Tokenでは、作成時に「Bypass 2FA」を有効にできます。従来は、この設定を有効にした書き込み用GATをCI/CDへ登録することで、2FAを要求される操作も自動実行できました。

しかし、漏えいしたトークンから新しいトークンを発行したり、攻撃者自身をパッケージのメンテナーに追加したりできる状態は、アカウント乗っ取りにつながります。

そこでnpmは、2026年7月31日から次のような操作をbypass-2FAの対象外としました。これらは、トークンではなく人が対話型2FAを通して実行する必要があります。(The GitHub Blog)

操作	bypass-2FA GATでの実行	推奨する対応
アクセストークンの作成・削除・権限変更	不可	WebまたはCLIで2FAを実行
メールアドレスやパスワードの変更	不可	npmアカウント画面から実行
2FA設定やリカバリー関連の変更	不可	対話型の本人確認を実行
パッケージのアクセス権変更	不可	WebまたはCLIで手動実行
メンテナーの追加・削除	不可	人が2FAを通して実行
Trusted Publishing設定の変更	不可	パッケージ設定画面から実行
組織・チームのメンバー管理	不可	npmの組織管理画面から実行
チームへのパッケージ権限付与	不可	対話型2FAで実行
プライベートパッケージの読み取り	利用可能	読み取り専用GATを使用
npm publishによる直接公開	現時点では利用可能	OIDCへの移行を開始
npm stage publish	利用可能	公開前承認が必要なら採用

npmの公式ドキュメントでは、2026年8月以降、メールアドレスやパスワードの変更、2FA設定、トークン管理、メンテナー管理、組織・チーム管理などを「account-identity」「account-governance」に分類し、常に対話型2FAを要求すると説明しています。(npm ドキュメント)

対象はnpm GATだけでGitHubのトークンには影響しない

今回の制限対象は、npmjs.comで作成するnpm Granular Access Tokenです。

次のGitHub側のトークンは、今回の変更対象ではありません。

• GitHub Personal Access Token
• GitHub Appのアクセストークン
• GitHub ActionsのGITHUB_TOKEN

GitHubは、今回の変更がこれらのGitHubトークンには影響しないことを明記しています。(The GitHub Blog)

ただし、対象外であることと、npmjs.orgの認証に代用できることは別です。

GITHUB_TOKENやGitHub PATは、主にGitHub APIやGitHub Packagesで使用するトークンです。npm公式レジストリであるregistry.npmjs.orgへの公開用トークンとして、単純にNPM_TOKENをGITHUB_TOKENへ置き換えることはできません。

GitHub Packagesのnpmレジストリは、通常、次のURLを使用します。

https://npm.pkg.github.com

一方、今回のnpm GAT制限やTrusted Publishingが対象とするnpm公式レジストリは、次のURLです。

https://registry.npmjs.org

GitHub Packagesでは、GitHub ActionsからGITHUB_TOKENを使って、ワークフローのリポジトリに関連付けられたパッケージを公開できます。レジストリがどちらなのかを最初に確認することが重要です。(GitHub Docs)

今回の制限が原因かを切り分ける方法

自動化が失敗したからといって、すべてがbypass-2FA GAT制限によるものとは限りません。次の順序で確認すると原因を絞り込めます。

使用しているレジストリを確認する

次のコマンドを実行します。

npm config get registry

表示結果が次の場合は、npm公式レジストリです。

https://registry.npmjs.org/

次の場合はGitHub Packagesです。

https://npm.pkg.github.com/

スコープごとにレジストリを変更している場合は、プロジェクトの.npmrcやpackage.jsonのpublishConfigも確認してください。

CI/CDで使用している資格情報を確認する

GitHub ActionsなどのSecretsに、次のような名前でnpmトークンが登録されていないか確認します。

NPM_TOKEN
NODE_AUTH_TOKEN
NPM_PUBLISH_TOKEN

変数名だけではトークンの種類は判断できません。npmjs.comのAccess Tokens画面で、対象トークンについて次を確認します。

• Granular Access Tokenであるか
• Read and write権限を持っているか
• Bypass 2FAが有効か
• 有効期限が切れていないか
• 対象パッケージやスコープが含まれているか
• 許可IPアドレスの制限に抵触していないか

失敗しているコマンドを確認する

2026年7月31日の変更が直接影響するのは、主に管理系の操作です。

例えば、次の処理をCI/CD内で実行している場合は今回の制限を疑います。

npm token
npm owner
npm access
npm team
npm org

独自スクリプトからnpm Registry APIを呼び出し、メンテナー、組織、チーム、パッケージ権限、Trusted Publishing設定を変更している場合も対象になる可能性があります。

一方、現時点でbypass-2FA GATを使ったnpm publishだけが失敗している場合は、今回の管理操作制限とは別の原因も確認してください。

• GATの有効期限切れ
• パッケージやスコープの指定不足
• Read-onlyトークンを使用している
• 間違ったレジストリへ接続している
• パッケージ設定でトークン公開が禁止されている
• .npmrcで別のトークンが上書きされている
• Trusted Publishingの設定が不一致になっている

npmの公式ドキュメントでも、bypass-2FA GATによる直接公開は現時点では可能とされています。したがって、2026年8月時点でnpm publishだけが失敗した場合、直ちに今回の制限が原因だと断定しないことが重要です。(npm ドキュメント)

機密管理操作はWebまたはCLIで対話的に実行する

トークン作成やメンテナー追加などの機密操作は、CI/CDから切り離します。

基本的な対応手順は次のとおりです。

1. CI/CDから管理系コマンドやAPI呼び出しを削除する
2. 管理者またはメンテナーがnpmへログインする
3. npmjs.comまたはローカルのnpm CLIで操作する
4. npmから求められた2FA認証を完了する
5. 変更結果を確認する
6. 必要に応じて変更記録を残す

CLIを使用する場合は、最初にログイン状態を確認します。

npm login
npm whoami

その後、必要な管理操作を実行し、表示される2FAフローを完了します。

2FAコードやセキュリティキーの認証情報をCI/CDのSecretに保存し、従来どおり無人実行しようとする方法は推奨されません。今回の変更は、人がその場にいることを確認する「proof of presence」を要求するためのものです。

また、GitHub PATやGITHUB_TOKENへ置き換えても、npm公式レジストリの管理操作を自動化する代替手段にはなりません。

自動公開はTrusted PublishingのOIDCへ移行する

人の承認なしでパッケージを自動公開したい場合は、Trusted Publishingを使用します。

Trusted Publishingでは、長期間有効なnpmトークンをCI/CDへ保存しません。GitHub ActionsがOIDCで短時間だけ有効な署名付き資格情報を取得し、登録済みのリポジトリとワークフローからのみ公開します。

トークンの漏えい、ローテーション忘れ、ログへの誤出力といった問題を減らせるため、npmは従来の公開トークンよりTrusted Publishingを推奨しています。(npm ドキュメント)

Trusted Publishingの主な要件

GitHub ActionsでTrusted Publishingを利用する場合は、次の要件を確認します。

項目	要件
npm CLI	11.5.1以降
Node.js	22.14.0以降
実行環境	GitHub-hosted runner
GitHub Actions権限	id-token: writeが必要
ワークフロー	.github/workflows配下に配置
Trusted Publisher	パッケージごとに1つ
リポジトリ情報	npm側の設定と完全一致が必要

現時点では、GitHub Actionsのself-hosted runnerはTrusted Publishingの対象外です。GitLab CI/CDとCircleCIもサポートされていますが、それぞれクラウド側の共有・ホスト環境を使用する必要があります。(npm ドキュメント)

npm側でTrusted Publisherを登録する

npmjs.comで対象パッケージを開き、次の順に進みます。

Packages
→ 対象パッケージ
→ Settings
→ Trusted Publisher

GitHub Actionsを選択し、次の項目を設定します。

• Organization or user
• Repository
• Workflow filename
• Environment name
• Allowed actions

Workflow filenameには、フルパスではなくファイル名だけを入力します。

例えば、ワークフローが次の場所にある場合、

.github/workflows/publish.yml

npm側には次のように入力します。

publish.yml

拡張子も必要です。大文字・小文字を含め、実際のファイル名と完全に一致させてください。

Allowed actionsでは、次のいずれかを選びます。

• npm publish
• npm stage publish
• 両方

公開前に必ず人の承認を入れたい場合は、npm stage publishだけを許可します。

GitHub ActionsにOIDC権限を追加する

GitHub Actionsの例は次のとおりです。

name: Publish to npm

on:
  push:
    tags:
      - "v*"

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: "24"
          registry-url: "https://registry.npmjs.org"
          package-manager-cache: false

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build --if-present

      - name: Test
        run: npm test

      - name: Publish
        run: npm publish

重要なのは次の設定です。

permissions:
  id-token: write
  contents: read

id-token: writeがないと、GitHub Actionsはnpmへ提示するOIDC IDトークンを取得できません。

Trusted Publishingで公開する場合、npm publishのステップに書き込み用のNODE_AUTH_TOKENを設定する必要はありません。npm CLIがOIDC環境を検出し、短時間だけ有効な公開用資格情報へ交換します。(npm ドキュメント)

プライベート依存関係がある場合

Trusted Publishingが置き換えるのは、基本的にnpm publishの認証です。

npm ciやnpm installでプライベートパッケージを取得する場合は、引き続き読み取り用トークンが必要になることがあります。この場合は、書き込み可能なbypass-2FA GATを使い回さず、読み取り専用GATを依存関係のインストール処理だけに設定します。

- name: Install private dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}

- name: Publish with OIDC
  run: npm publish

読み取り用トークンをジョブ全体へ設定せず、必要なステップだけに渡すのが安全です。(npm ドキュメント)

Trusted Publishingで失敗しやすいポイント

OIDCへ移行した後にENEEDAUTHや認証エラーが発生する場合は、次の項目を確認します。

id-token: writeが不足している

次の権限がワークフローに必要です。

permissions:
  contents: read
  id-token: write

リポジトリや組織の既定権限を変更していても、ワークフロー内で明示しておくと判断しやすくなります。

ワークフローファイル名が一致していない

次の違いでも認証に失敗します。

publish.yml
Publish.yml
publish.yaml
release.yml

npm側にはフルパスを登録せず、拡張子を含むファイル名だけを登録します。

Environment名が一致していない

npm側のTrusted Publisher設定でEnvironmentを指定した場合は、GitHub Actionsのジョブにも同じEnvironmentを設定します。

jobs:
  publish:
    environment: npm

大文字・小文字を含め、npm側の登録内容と一致させてください。

self-hosted runnerを使用している

GitHub ActionsのTrusted Publishingは、現時点ではGitHub-hosted runnerが必要です。

次の設定は対象です。

runs-on: ubuntu-latest

次のようなself-hosted runnerは対象外です。

runs-on: self-hosted

package.jsonのrepositoryが一致していない

GitHubから公開する場合、package.jsonのrepository.urlが実際のGitHubリポジトリと一致している必要があります。

{
  "repository": {
    "type": "git",
    "url": "https://github.com/example-org/example-package.git"
  }
}

移行済みのリポジトリ、フォーク、リポジトリ名を変更したプロジェクトでは特に注意してください。

workflow_callで呼び出している

再利用可能ワークフローからnpm publishしている場合、npm側の検証対象が、実際に公開コマンドを持つ子ワークフローではなく、呼び出し元ワークフローになる場合があります。

親と子の両方にOIDC権限が必要になるケースもあるため、通常のワークフローへ一時的に戻して切り分けると原因を確認しやすくなります。

npm whoamiでOIDCを確認しようとしている

Trusted PublishingのOIDC認証は、npm publishやnpm stage publishの実行時に行われます。

そのため、次のコマンドがOIDC認証の成功を示すわけではありません。

npm whoami

OIDC設定は、テスト用パッケージやプレリリースタグなどを使って実際の公開フローで確認します。npm側のTrusted Publisher設定は、保存時に入力内容の正しさが検証されず、公開時に初めて不一致が判明する点にも注意が必要です。(npm ドキュメント)

人の承認を残すならStaged Publishingへ移行する

公開前にメンテナーがパッケージ内容を確認したい場合は、Staged Publishingを使用します。

Staged Publishingでは、CI/CDがパッケージを直接公開せず、まずnpmのステージ領域へ送信します。その後、人が内容を確認し、2FAを通して承認すると正式公開されます。(npm ドキュメント)

処理の流れは次のとおりです。

CI/CDでビルド・テスト
↓
npm stage publish
↓
npm上でパッケージを確認
↓
メンテナーが2FAで承認
↓
正式公開

Staged Publishingの要件

項目	要件
npm CLI	11.15.0以降
Node.js	22.14.0以降
npmアカウント	2FAが有効
パッケージ	npmレジストリに既に存在する
権限	対象パッケージへの公開権限

Staged Publishingでは、新規パッケージの初回公開をステージできません。パッケージがnpmレジストリにまだ存在しない場合は、最初の公開を対話的に実行する必要があります。

CI/CDからパッケージをステージする

直接公開していた次のコマンドを、

npm publish

次のコマンドへ変更します。

npm stage publish

GitHub Actionsでは次のように記述できます。

- name: Stage package
  run: npm stage publish

Trusted Publishingと組み合わせる場合は、npm側のAllowed actionsでnpm stage publishを許可します。

より厳格に運用するなら、npm publishを許可せず、ステージだけを許可してください。これにより、設定ミスやワークフロー改ざんがあっても、人の承認を経ずに直接公開されるリスクを抑えられます。

ステージされたパッケージを確認する

CLIから一覧を表示します。

npm stage list

特定のパッケージに絞る場合は、パッケージ名を指定します。

npm stage list example-package

ステージの詳細を確認します。

npm stage view <stage-id>

tarballをダウンロードして内容を確認することもできます。

npm stage download <stage-id>

npmjs.comの「Staged Packages」画面から確認する方法もあります。

2FAで承認して正式公開する

確認後、CLIから承認します。

npm stage approve <stage-id>

npmjs.comのStaged Packages画面から「Approve」を選ぶこともできます。

npm stage publish自体は2FAを要求しませんが、npm stage approveは対話型2FAを要求します。CI/CDによる作成と、人による最終承認を分離できる仕組みです。(npm ドキュメント)

OIDCとStaged Publishingはどちらを選ぶべきか

Trusted PublishingとStaged Publishingは、どちらか一方だけを選ぶ仕組みではありません。Trusted Publishingで認証し、Staged Publishingで人の承認を追加することもできます。

方式	自動公開	人の2FA承認	長期トークン	適した運用
bypass-2FA GATで直接公開	可能だが廃止予定	不要	必要	移行前の暫定運用
Trusted Publishingで直接公開	可能	不要	不要	完全自動リリース
GATでStaged Publishing	ステージまで可能	必要	必要	self-hosted環境の暫定対応
Trusted Publishing＋Staged Publishing	ステージまで可能	必要	不要	セキュリティ重視
ローカルから対話的に公開	不可	必要	不要	小規模・低頻度の公開

リリース頻度が高く、テスト完了後に自動公開してよいパッケージはTrusted Publishingによる直接公開が適しています。

重要なライブラリ、利用者の多いパッケージ、公開物を人が確認したい組織では、Trusted PublishingとStaged Publishingを組み合わせる方法が適しています。

GitHub Environmentの承認機能を使う方法もありますが、承認のタイミングが異なります。

• GitHub Environment：公開ジョブを実行する前に承認
• Staged Publishing：npmへ送信された公開予定のtarballを確認してから承認

実際にnpmへ送るファイルを確認したい場合は、Staged Publishingの方が目的に合います。

self-hosted runnerを使用している場合の対応

Trusted Publishingは、現時点ではself-hosted runnerに対応していません。

self-hosted環境を維持する必要がある場合は、次のいずれかを検討します。

• 公開処理だけGitHub-hosted runnerへ分離する
• self-hosted runnerからnpm stage publishを実行する
• ステージ後、人がCLIまたはnpmjs.comで承認する

npm stage publishは2FAを要求しないため、bypass-2FAを有効にしていないGATでも自動化できます。npmの公式ドキュメントでも、bypass-2FA GATを削除し、Trusted PublishingまたはbypassなしGATによるStaged Publishingへ切り替えることが推奨されています。(npm ドキュメント)

ただし、GATを残す場合は次を徹底してください。

• 対象パッケージを限定する
• 必要最小限の書き込み権限にする
• 有効期限を短くする
• 可能ならIPアドレスを制限する
• Secretを公開ジョブだけに渡す
• 定期的に利用状況を監査する

2027年1月までに直接publishを移行する

2026年7月31日の変更では、bypass-2FA GATによる直接のnpm publishは直ちに停止されていません。

ただしGitHubは、2027年1月を目標に、bypass-2FA GATから直接公開権限を削除する方針を示しています。変更後に残る予定の用途は、主に次の2つです。

• プライベートパッケージの読み取り
• npm stage publishによるステージ送信

つまり、次のような従来の設定は将来的に失敗する可能性があります。

- name: Publish
  run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

公開頻度が低いパッケージであっても、期限直前まで放置すると、リリースが必要なタイミングで初めて停止に気づくことになります。

少なくとも次の順序で移行してください。

1. 現在の公開ワークフローとnpm GATを棚卸しする
2. 管理操作をCI/CDから切り離す
3. Trusted Publisherを設定する
4. OIDCによる公開をテストする
5. 必要に応じてStaged Publishingへ切り替える
6. 不要になったbypass-2FA GATを削除する
7. パッケージ側でトークン公開を禁止する

2027年1月は確定日ではなく、GitHubが示している目標時期です。実際の適用日や移行条件は変更される可能性があるため、公式Changelogとnpmドキュメントも継続して確認してください。(The GitHub Blog)

移行後はトークンによる公開を禁止する

Trusted PublishingまたはStaged Publishingの動作確認が完了したら、npmパッケージの設定を強化します。

npmjs.comで次の場所を開きます。

Packages
→ 対象パッケージ
→ Settings
→ Publishing access

次の設定を選択します。

Require two-factor authentication and disallow tokens

この設定を有効にすると、bypass-2FAの有無にかかわらず、従来型のGATを使った直接公開が禁止されます。Trusted Publishingは従来型のトークン認証ではなくOIDCを使用するため、引き続き動作します。(npm ドキュメント)

安全に移行する順番は次のとおりです。

1. Trusted Publishingを設定する
2. 実際に公開またはステージできることを確認する
3. Publishing accessでトークンを禁止する
4. CI/CDから書き込み用npmトークンを削除する
5. npmアカウントから不要なGATを失効させる

先にトークンを削除すると、OIDCの設定ミスがあった場合に公開手段を失います。必ず新しい公開方式の動作確認後に削除してください。

まとめ

npmのbypass-2FA GATを使った自動化が2026年7月31日以降に失敗する場合は、まず実行している操作を確認してください。

トークン管理、メンテナー変更、パッケージアクセス設定、Trusted Publishing設定、組織・チーム管理などは、bypass-2FA GATでは実行できません。WebまたはCLIから、対話型2FAを通して操作する必要があります。

自動公開については、次の基準で移行先を選びます。

• 完全自動で公開したい：Trusted PublishingによるOIDC
• 公開前に人が確認したい：Trusted Publishing＋Staged Publishing
• self-hosted runnerを継続したい：GATによるステージ送信＋人の2FA承認

bypass-2FA GATによる直接公開は現時点では動作しますが、2027年1月を目標に廃止される予定です。まずCI/CD内のNPM_TOKENとnpm管理コマンドを棚卸しし、OIDCによる公開テストから着手してください。