Github Actions中Mkdocs与Docker容器协同异常问题排查

一、直接用Github Actions执行mkdocs gh-deploy时mkdocstrings失效的原因及解决 #

原因 #

1. 依赖不全：mkdocstrings生成Python文档需要mkdocstrings[python]、griffe等额外依赖，默认工作流可能未安装这些包。
2. 源码读取受限：Github Actions默认的actions/checkout若使用浅克隆（fetch-depth默认1），会导致mkdocstrings无法读取完整源码结构。
3. 配置错误：mkdocs.yml中mkdocstrings的源码路径配置不正确，无法定位要生成文档的代码。

解决方法 #

1. 安装完整依赖：在工作流中添加依赖安装步骤，可直接指定包或用项目的requirements.txt批量安装：

   - name: Install dependencies
     run: pip install mkdocs mkdocstrings[python] griffe
   

   或者：

   - name: Install dependencies
     run: pip install -r requirements.txt
   

2. 完整克隆仓库：修改actions/checkout步骤，确保拉取完整代码：

   - name: Checkout full code
     uses: actions/checkout@v4
     with:
       fetch-depth: 0
   

3. 检查mkdocs.yml配置：确认mkdocstrings指定了正确的源码路径，比如源码在src目录：

   plugins:
     - mkdocstrings:
         default_handler: python
         handlers:
           python:
             paths: [src]
   

二、Docker容器在Github Actions中运行时Mkdocs无法识别环境的原因及解决 #

原因 #

1. 环境变量未传递：Mkdocs通过GITHUB_ACTIONS、GITHUB_TOKEN等环境变量判断运行环境，Docker容器默认不会继承这些变量，导致部署逻辑异常。
2. 目录挂载与权限问题：Github Actions中挂载工作区目录时，容器内用户可能无读写权限，或挂载路径与容器内工作目录不匹配。
3. 容器内Git未配置：mkdocs gh-deploy需要Git提交内容，容器内未配置Git用户名、邮箱会导致部署失败。

解决方法 #

1. 传递必要环境变量：运行容器时通过-e参数传入Github Actions的环境变量：

   - name: Deploy with Docker
     run: |
       docker run \
         -e GITHUB_ACTIONS=true \
         -e GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} \
         -e GITHUB_REPOSITORY=${{ github.repository }} \
         -v ${{ github.workspace }}:/app \
         your-docker-image mkdocs gh-deploy --force
   

2. 确保权限与路径匹配：在Dockerfile中设置容器内工作目录为挂载路径（如WORKDIR /app），若遇权限问题，可临时以root用户运行容器：

   - name: Deploy with Docker
     run: |
       docker run \
         --user root \
         -e GITHUB_ACTIONS=true \
         -e GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} \
         -v ${{ github.workspace }}:/app \
         your-docker-image mkdocs gh-deploy --force
   

3. 配置Git信息：可在Dockerfile中提前配置Git信息：

   RUN apt-get update && apt-get install -y git
   RUN git config --global user.name "github-actions[bot]"
   RUN git config --global user.email "github-actions[bot]@users.noreply.github.com"
   

   或在运行容器时临时配置：

   - name: Deploy with Docker
     run: |
       docker run \
         -e GITHUB_ACTIONS=true \
         -e GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} \
         -v ${{ github.workspace }}:/app \
         your-docker-image \
         sh -c "git config --global user.name 'github-actions[bot]' && git config --global user.email 'github-actions[bot]@users.noreply.github.com' && mkdocs gh-deploy --force"
   

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