skillhub-179-ts-library/references/ci-workflows.md

CI 工作流

基础 CI

# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install
      - run: pnpm lint

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install
      - run: pnpm typecheck

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install
      - run: pnpm test

矩阵测试

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest]
        node: [20, 22, 24]
        include:
          - os: macos-latest
            node: 24
          - os: windows-latest
            node: 24
      fail-fast: false
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: pnpm
      - run: pnpm install
      - run: pnpm test

跳过纯文档变更

jobs:
  changed:
    runs-on: ubuntu-latest
    outputs:
      should_skip: ${{ steps.check.outputs.only_changed == 'true' }}
    steps:
      - uses: tj-actions/changed-files@v47
        id: check
        with:
          files: |
            docs/**
            **.md

  test:
    needs: changed
    if: needs.changed.outputs.should_skip != 'true'
    # ... 其余任务配置

自动修复提交

- run: pnpm lint:fix
- uses: stefanzweifel/git-auto-commit-action@v5
  if: github.event_name == 'push'
  with:
    commit_message: 'chore: lint fix'

标签发布（基于 Token）

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
          registry-url: https://registry.npmjs.org
      - run: pnpm install
      - run: pnpm build
      - run: pnpm publish --access public --no-git-checks
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

标签发布（OIDC — 推荐做法）

无需 NPM_TOKEN。使用 GitHub OIDC 实现免 Token 认证并附带来源证明（provenance）。

name: Release
permissions:
  id-token: write
  contents: write
  actions: read
on:
  push:
    tags: ['v*']

jobs:
  wait-for-ci:
    runs-on: ubuntu-latest
    steps:
      - uses: lewagon/wait-on-check-action@v1.3.4
        with:
          ref: ${{ github.sha }}
          check-name: ci
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          wait-interval: 10

  release:
    needs: wait-for-ci
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24  # 必需：npm 11.5.1+
          cache: pnpm
          registry-url: https://registry.npmjs.org
      - run: pnpm install
      - run: pnpm build
      - run: pnpm dlx changelogithub
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: pnpm publish --access public --no-git-checks --provenance

OIDC 配置步骤

1. 打开 https://www.npmjs.com/package/<PACKAGE_NAME>/access
2. 滚动至「Publishing access」区域
3. 在「Trusted Publishers」下点击「Add GitHub Actions」
4. 填写：Owner（所有者）、Repository（仓库）、Workflow file（工作流文件，release.yml）、Environment（环境，留空）
5. 点击「Add」

OIDC 要求

1. Node.js 24+（需要 npm 11.5.1+——Node 22 自带的 npm 10.x 会失败）
2. 权限（Permissions）：id-token: write
3. 发布标志：--provenance
4. package.json：必须包含 repository 字段
5. npm 两步验证（2FA）：设置为「需要 2FA 或粒度访问令牌」（允许 OIDC）

故障排查

错误信息	原因	修复方法
"Access token expired" E404	npm 版本过旧	使用 Node.js 24
ENEEDAUTH	缺少 registry-url	在 setup-node 中添加 registry-url
"repository.url is empty" E422	缺少字段	在 package.json 中添加 repository
"not configured as trusted publisher"	配置不匹配	检查 owner、repo、workflow 是否完全一致

单体仓库矩阵

jobs:
  test:
    strategy:
      matrix:
        package: [core, utils, cli]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install
      - run: pnpm --filter ${{ matrix.package }} test

并发控制

取消过时的运行：

concurrency:
  group: ${{ github.workflow }}-${{ github.event.number || github.sha }}
  cancel-in-progress: true

针对 PR 的 pkg-pr-new

# .github/workflows/pkg-pr-new.yml
name: Publish PR
on: pull_request

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install
      - run: pnpm build
      - run: pnpm dlx pkg-pr-new publish --compact --pnpm

CI 中的包验证

- run: pnpm build
- run: pnpm dlx publint
- run: pnpm dlx @arethetypeswrong/cli --pack .