GitHub Actions 流水线注入敏感配置完整方案（Antora + Docker Compose）

核心安全准则

1. 敏感信息全部存仓库 Secrets ，绝不写代码、不提交 .env；
2. 密钥只通过环境变量透传给容器，不落地明文文件；
3. 日志自动掩码 Secrets，不会打印 Token/AK 明文；
4. 构建完成无残留凭证。

一、第一步：存储敏感密钥（仓库 Secrets）

1. 仓库 → Settings → Secrets and variables → Actions → New repository secret
2. 添加你项目需要的密钥，示例清单：
   | Secret 名称 | 用途 |
   |------|------|
   | DOC_GIT_PAT | GitHub Personal Token，拉取私有 AsciiDoc 文档仓库 |
   | DOC_GIT_USER | 私有仓库用户名 |
   | DEPLOY_SITE_TOKEN | 静态站点部署密钥（如 Pages/OSS/CDN） |
   | DOCKER_REG_PWD | 私有镜像仓库密码（自定义 Antora 镜像才需要） |

二、两种注入方案（按需选择）

方案1：环境变量直接透传容器（推荐，无 .env 临时文件）

原理：Actions 读取 Secrets → 作为环境变量传给 docker-compose run -e → Antora 构建容器内直接读取，全程无磁盘明文。

1. 流水线文件 .github/workflows/build-docs.yml

name: Build Antora Docs
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 构建工程代码（docker-compose/playbook等）
        uses: actions/checkout@v4

      - name: 拉取文档源码私有仓库（可选，也可交给Antora内置Git拉取）
        uses: actions/checkout@v4
        with:
          repository: your-org/fortigate-doc-src
          path: docs-src
          token: ${{ secrets.DOC_GIT_PAT }}

      - name: 使用Docker Compose构建文档
        env:
          # 把仓库Secrets注入当前Action环境变量
          GIT_DOC_USER: ${{ secrets.DOC_GIT_USER }}
          GIT_DOC_TOKEN: ${{ secrets.DOC_GIT_PAT }}
          TZ: Asia/Shanghai
        run: |
          # 将Action环境变量透传给Antora容器
          docker-compose run --rm \
            -e GIT_DOC_USER="$GIT_DOC_USER" \
            -e GIT_DOC_TOKEN="$GIT_DOC_TOKEN" \
            -e TZ="$TZ" \
            antora-builder

      - name: 上传构建产物（网页+PDF）
        uses: actions/upload-artifact@v4
        with:
          name: docs-output
          path: build-output/

2. antora-playbook.yml 读取容器内环境变量拉取私有仓库

content:
  sources:
    # 私有Git仓库，拼接Token鉴权
    - url: https://${GIT_DOC_USER}:${GIT_DOC_TOKEN}@github.com/your-org/fortigate-doc-src.git
      branches: HEAD
      start_path: docs

方案2：动态生成临时 .env（需要.env文件场景）

仅适合部分扩展工具必须读取 .env 文件的场景，构建后立刻删除，不会留存敏感文件：

run: |
  # 运行时临时生成.env，不提交仓库
  cat > .env << EOF
GIT_DOC_USER=$GIT_DOC_USER
GIT_DOC_TOKEN=$GIT_DOC_TOKEN
EOF
  docker-compose run --rm antora-builder
  # 构建完成立即销毁敏感文件
  rm -f .env

三、扩展场景：私有Docker镜像仓库鉴权

如果你自己打包 Antora 私有镜像，需要登录镜像仓库再构建：

- name: 登录私有容器仓库
  env:
    DOCKER_USER: ${{ secrets.DOCKER_REG_USER }}
    DOCKER_PWD: ${{ secrets.DOCKER_REG_PWD }}
  run: |
    echo "$DOCKER_PWD" | docker login ghcr.io -u $DOCKER_USER --password-stdin

四、产物自动部署 GitHub Pages（完整发布链路）

构建出静态网页后，直接推送 GitHub Pages，部署密钥无需额外配置，使用内置 GITHUB_TOKEN：

- name: 部署静态文档到 GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ github.TOKEN }}
    publish_dir: ./build-output/site

五、关键安全注意事项

1. 禁止在日志打印密钥
   不要写 echo $GIT_DOC_TOKEN，GitHub 会自动掩码 Secrets，但主动打印无意义且有风险。
2. 不要将 .env 提交进仓库
   .gitignore 必须包含 .env，本地开发用的.env仅本地留存，不推远程。
3. 细粒度 PAT 权限
   拉取私有文档仓库的 PAT 只赋予 repo 权限，不要给全局高权限。
4. 不缓存构建目录
   Actions 默认不会缓存 build-output，避免密钥意外存入缓存快照。
5. 容器内禁止输出凭证
   adoc、PDF、网页产物中不要打印 Git Token、AK/SK 等敏感字段。

六、本地开发与CI区分小技巧

本地写文档时使用本地 .env（不提交），CI流水线自动覆盖注入正式密钥，一套 compose 同时适配本地+线上流水线，无需修改配置。