基于GitHub Action构建Python依赖的最佳实践及Release Tags回滚咨询

一、先锁定精确依赖版本 #

原来的范围依赖（如package>=3.0,<4.0）会导致每次构建拉取最新版本，无法保证一致性。首先要生成包含精确版本号的依赖文件：

• 用pip的话，在虚拟环境中安装基础依赖后执行：

  pip freeze > requirements.txt
  

  注意：确保仅包含项目实际依赖，避免混入系统或虚拟环境自带包。
• 用Poetry/Pipenv的话，直接用自带的poetry.lock/Pipfile.lock锁文件，这类文件不仅记录精确版本，还能完整保留依赖树关系，比pip freeze更可靠。

二、GitHub Action流水线实现依赖包打包存储 #

在.github/workflows/deps-bundle.yml中编写流水线，完成依赖下载、压缩、存储的全流程：

核心流程步骤 #

• 触发条件：可设置为主分支推送、Tag创建或手动触发，兼顾日常更新和版本标记需求：

  on:
    push:
      branches: [ main ]
    create:
      tags:
        - 'deps-v*'
    workflow_dispatch: # 手动触发入口
  

• 环境准备：拉取代码并匹配项目Python版本：

  jobs:
    bundle-deps:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - name: Set up Python
          uses: actions/setup-python@v5
          with:
            python-version: '3.x' # 替换为你的项目Python版本
  

• 下载并打包依赖：根据锁文件拉取所有依赖到本地目录，再压缩归档：

  - name: Download dependencies
          run: |
            python -m pip install --upgrade pip
            pip download -r requirements.txt -d ./deps-packages
        - name: Bundle dependencies
          run: tar -czf deps-bundle-${{ github.ref_name }}.tar.gz ./deps-packages
  

• 存储依赖包：
  1. 若存到代码仓库：将压缩包提交推回（需通过条件判断避免流水线无限循环）；
  2. 更推荐绑定Release Tag：创建deps-vx.y.z格式的Tag时，自动将压缩包作为Release附件上传，方便后续回滚：

     - name: Upload to Release
          if: startsWith(github.ref, 'refs/tags/deps-v')
          uses: actions/upload-release-asset@v1
          env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          with:
            upload_url: ${{ github.event.release.upload_url }}
            asset_path: ./deps-bundle-${{ github.ref_name }}.tar.gz
            asset_name: deps-bundle-${{ github.ref_name }}.tar.gz
            asset_content_type: application/gzip
     

三、基于Release Tag的依赖回滚方案 #

当新依赖出现问题时，直接切换到对应版本的Release Tag，使用当时的依赖包快速恢复：

• 在部署流水线中添加逻辑：若指定旧的deps-vx.y.z Tag，就下载对应压缩包，解压后从本地包安装，无需访问PyPI：

  # 解压依赖包
  tar -xzf deps-bundle-${TAG_NAME}.tar.gz
  # 从本地包安装，跳过远程源
  pip install --no-index --find-links=./deps-packages -r requirements.txt
  

• 日常构建默认使用最新依赖包；出现问题时，手动指定回滚到历史Tag即可完成快速恢复。

四、额外注意事项 #

• 避免冗余：打包前清理临时文件，仅保留.whl或.tar.gz格式的依赖包；
• 锁文件维护：定期更新锁文件（如每月一次），但更新后必须经过完整测试，再生成新的依赖包和Tag；
• 权限配置：确保GitHub Action拥有推送代码或上传Release附件的权限，可使用默认GITHUB_TOKEN或自定义Token。

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