GitHub Action故障排查：自动化Release与PyPI包版本更新失败

因为看不到你的具体YAML代码，下面列这类场景下最容易触发错误的坑：

1. 触发条件配置错了 #

• 提交消息匹配规则写法不对，比如直接在on.push里写message字段（GitHub Action不支持这种写法），或者正则匹配逻辑有问题
• 错误示例：

  on:
    push:
      branches: main
      message: "Release v*"  # 这里写法无效
  

• 正确姿势：在job里加条件判断

  on: [push]
  jobs:
    release:
      if: startsWith(github.event.head_commit.message, 'Release v')
      runs-on: ubuntu-latest
      # 后续步骤...
  

2. 版本号提取失败 #

• 从提交消息里抠版本号的命令太粗糙，比如用cut分割时没考虑空格或格式差异，导致后续PyPI上传版本无效
• 错误示例：

  - name: Get version
    run: echo "VERSION=$(echo ${{ github.event.head_commit.message }} | cut -d' ' -f2)" >> $GITHUB_ENV
  

• 更严谨的写法用正则匹配：

  - name: Extract version
    run: echo "VERSION=$(echo "${{ github.event.head_commit.message }}" | grep -oP 'Release v\K\d+\.\d+\.\d+')" >> $GITHUB_ENV
  

3. PyPI 认证出问题 #

• 要么是GitHub Secrets里的PyPI Token名称写错，要么是用了用户名密码而非官方推荐的token，导致上传时返回401权限错误
• 错误示例：

  - name: Upload to PyPI
    uses: pypa/gh-action-pypi-publish@v1.8.10
    with:
      user: __token__
      password: ${{ secrets.PYPI_KEY }}  # 要是你Secrets里存的名字是PYPI_TOKEN就会报错
  

• 注意：PyPI的token必须是项目级别的，并且要在GitHub仓库的Secrets里正确添加

4. Release 提交记录生成失败 #

• git log的范围不对，比如只取了当前提交的上一条，没拿到上次Release之后的所有提交，导致Release内容为空或不全
• 错误示例：

  - name: Generate notes
    run: echo "RELEASE_NOTES=$(git log --oneline HEAD^..HEAD)" >> $GITHUB_ENV
  

• 正确写法（自动找上次Release的提交）：

  - name: Generate release notes
    run: |
      # 找到最近一条带Release标记的提交
      LAST_RELEASE_COMMIT=$(git log --grep="Release v" --max-count=1 --format="%H")
      # 提取该提交到当前的所有记录
      echo "RELEASE_NOTES=$(git log $LAST_RELEASE_COMMIT..HEAD --oneline)" >> $GITHUB_ENV
  

5. 打包环节依赖缺失 #

• 没提前安装setuptools、wheel这些打包必备工具，或者setup.py/pyproject.toml配置有问题，导致打包失败
• 错误示例：

  - name: Build package
    run: python setup.py sdist bdist_wheel
  

• 先装依赖再打包：

  - name: Install build tools
    run: pip install setuptools wheel twine
  - name: Build package
    run: python -m build
  

6. GitHub Release 权限不足 #

• 默认的GITHUB_TOKEN没有创建Release的权限，必须在job里明确设置权限
• 正确配置：

  jobs:
    release:
      permissions:
        contents: write  # 必须开这个权限才能创建Release
      runs-on: ubuntu-latest
      # 后续步骤...
  

内容的提问来源于stack exchange，提问作者Md. Musfiqur Rahaman