GitHub 自托管 Runner 找不到 Python 解决方案

本文旨在帮助开发者解决在使用 GitHub 自托管 Runner 时，`actions/setup-python` 无法找到指定 Python 版本的问题。我们将分析可能的原因，并提供详细的解决方案，确保你的 CI/CD 流程顺利运行。核心问题在于自托管 Runner 的操作系统与 `setup-python` action 的兼容性。

问题分析

当你在 GitHub 自托管 Runner 中使用 actions/setup-python action 时，可能会遇到以下错误：

Run actions/setup-python@v3
Version 3.9 was not found in the local cache
Error: Version 3.9 with arch x64 not found
The list of all available versions can be found here: `https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json`

这通常表示 action 无法在 Runner 的环境中找到你指定的 Python 版本。

解决方案

1. 操作系统兼容性

actions/setup-python action 对 Runner 的操作系统有特定的要求。根据官方文档，Python distributions 只在 GitHub Actions hosted environments 可用的操作系统上提供。这意味着，如果你的自托管 Runner 使用了不受支持的 Linux 发行版（例如 AlmaLinux、Fedora 等），setup-python action 可能无法正常工作。

解决方案：

• 更换操作系统： 推荐使用 Ubuntu 或 Windows 等 GitHub Actions hosted environments 支持的操作系统。这是最直接有效的解决方案。

• Docker 容器： 使用 Docker 容器来运行你的 CI/CD 流程。你可以创建一个包含所需 Python 版本的 Docker 镜像，并在 Runner 中运行该镜像。

  示例 Dockerfile:

  FROM ubuntu:latest
  
  # 安装 Python 3.9
  RUN apt-get update && apt-get install -y python3.9 python3-pip
  
  # 设置 Python 3.9 为默认 Python 版本
  RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.9 1
  
  # 安装其他依赖
  RUN pip3 install --upgrade pip
  RUN pip3 install flake8 pytest
  
  # 设置工作目录
  WORKDIR /app
  
  # 复制项目文件
  COPY . /app
  
  # 定义运行命令
  CMD ["pytest"]

  然后，在你的 workflow 文件中，使用 Docker 镜像来运行你的测试：

  name: Python application
  
  on:
    push:
      branches: [ "main" ]
    pull_request:
      branches: [ "main" ]
  
  permissions:
    contents: read
  
  jobs:
    build:
      runs-on: self-hosted
  
      steps:
      - uses: actions/checkout@v3
      - name: Build and run Docker container
        run: |
          docker build -t my-python-app .
          docker run my-python-app

2. 检查 Python 版本清单

如果你的操作系统是受支持的，但仍然遇到问题，请检查 https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json 上的 Python 版本清单，确认你指定的 Python 版本是否确实存在。

3. 手动安装 Python

如果 setup-python action 仍然无法工作，你可以尝试手动在 Runner 上安装 Python。

示例 (Ubuntu):

sudo apt update
sudo apt install python3.9

然后，在你的 workflow 文件中，直接使用 python3.9 命令：

name: Python application

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

permissions:
  contents: read

jobs:
  build:
    runs-on: self-hosted

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python 3.9
      run: |
        python3.9 -m pip install --upgrade pip
        pip3.9 install flake8 pytest
        if [ -f requirements.yml ]; then pip3.9 install -r requirements.yml; fi
    - name: Lint with flake8
      run: |
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest *.py

注意事项：

• 确保手动安装的 Python 版本与你的代码和依赖项兼容。
• 如果手动安装了多个 Python 版本，需要正确配置 PATH 环境变量，以便系统能够找到正确的 Python 可执行文件。

4. Conda 环境 (如果使用)

如果你使用 Conda 管理 Python 环境，确保 Conda 已正确安装和配置，并且你的 workflow 文件中正确激活了 Conda 环境。

name: Python application

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

permissions:
  contents: read

jobs:
  build:
    runs-on: self-hosted

    steps:
    - uses: actions/checkout@v3
    - name: Set up Conda
      uses: conda-incubator/setup-miniconda@v2
      with:
        activate-environment: flow_corrections
        environment-file: requirements.yml
        python-version: 3.10
    - name: Install dependencies
      shell: bash  # Ensure bash shell is used for conda commands
      run: |
        conda env update --file requirements.yml --name flow_corrections --prune
        pip install -r requirements.txt  # If you have a requirements.txt file
    - name: Lint with flake8
      run: |
        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
    - name: Test with pytest
      run: |
        pytest *.py

注意事项：

• 确保 requirements.yml 文件中的 Python 版本与 conda-incubator/setup-miniconda action 中指定的 python-version 匹配。
• 使用 conda env update 命令可以确保 Conda 环境与 requirements.yml 文件保持同步。

总结

解决 GitHub 自托管 Runner 无法找到 Python 版本的问题，通常需要考虑操作系统兼容性、Python 版本清单、手动安装 Python 以及 Conda 环境配置等因素。选择合适的解决方案，可以确保你的 CI/CD 流程顺利运行。如果问题仍然存在，请仔细检查错误日志，并参考 GitHub Actions 和 setup-python action 的官方文档。