解决GitHub Actions中私有npm包权限错误及仓库检出失败问题

问题根源 #

1. 默认GITHUB_TOKEN是当前仓库专属令牌，仅能访问Workflow所在仓库的资源，无法跨仓库读取另一个私有npm包。
2. 全局设置permissions: { packages: read }会覆盖GitHub默认权限集，默认的contents: read权限被移除，导致代码检出失败。
3. 全量赋予write权限无效，因为默认令牌本身不具备跨仓库访问权限。

解决方案 #

方案一：使用个人访问令牌（PAT，推荐个人/小团队场景） #

这是最直接的跨仓库权限解决方案：

1. 生成带权限的PAT：
   • 进入GitHub个人设置 → Developer settings → Personal access tokens → Tokens (classic)
   • 生成新令牌，勾选read:packages权限，确保你的GitHub账号有权限访问目标私有npm包所在仓库/组织。
2. 存储PAT到项目Secrets：
   • 打开应用项目的GitHub仓库 → Settings → Secrets and variables → Actions
   • 新建Secret，命名为GH_PAT，粘贴刚才生成的PAT。
3. 修正Workflow配置：
   • 同时保留代码检出所需的contents: read和私有包读取所需的packages: read权限
   • 替换默认GITHUB_TOKEN为自定义PAT

修正后的完整Workflow示例：

name: Workflow

# 保留你的触发器配置（比如on: push/pull_request等）

permissions:
  contents: read  # 必须保留，用于检出当前仓库代码
  packages: read  # 赋予私有npm包读取权限

jobs:
  workflow:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4  # 确保存在代码检出步骤

      - name: Setup npm auth for GitHub Packages
        run: npm config set //npm.pkg.github.com/:_authToken=${{ secrets.GH_PAT }}

      - name: Install dependencies
        run: npm install

      # 后续步骤...

方案二：组织级仓库依赖配置（适合同组织内团队场景） #

如果两个仓库属于同一个GitHub组织，可通过配置仓库依赖关系使用默认GITHUB_TOKEN：

1. 配置私有包仓库的依赖访问：
   • 打开私有npm包所在仓库 → Settings → Actions → General
   • 在「Workflow permissions」区域，选择「Read repository contents and packages permissions」
   • 滚动到「Repository access」，添加应用项目仓库为授权访问的依赖仓库。
2. 修正应用项目的Workflow权限：
   同样需要同时设置contents: read和packages: read，无需替换GITHUB_TOKEN。

常见排查点 #

• 确认PAT的read:packages权限已勾选，且账号能直接访问目标私有npm包仓库。
• 确保.npmrc中的@company scope与私有包的scope完全一致（大小写敏感）。
• 不要在Workflow中重复覆盖registry配置，保持原有.npmrc即可。

内容的提问来源于stack exchange，提问作者baitendbidz