如何在Semaphore CI流水线中实现构建产物推送回Git仓库

针对Sphinx文档构建后推送至GitHub Pages托管分支的场景，可按以下流程配置流水线，实现代码拉取、产物构建、分支回推的全自动化：

前置配置 #

• 在GitHub侧生成具备目标仓库内容读写权限的个人访问令牌（PAT）
• 进入Semaphore CI对应项目的环境变量配置页，将生成的令牌保存为私密环境变量，命名为GIT_PUSH_TOKEN，禁止将令牌明文写入流水线配置文件

流水线核心流程 #

• 配置触发规则：仅当main分支接收到合并提交时触发流水线，自动拉取main分支的最新文档源码
• 构建环境初始化：在构建任务中安装Sphinx及文档依赖，执行标准构建命令生成HTML静态产物，默认输出路径为_build/html目录
• 产物推送逻辑：构建完成后自动完成Git身份配置、目标分支拉取、产物替换、提交推送全流程

可直接复用的核心执行脚本 #

# 配置CI提交身份信息
git config --global user.name "semaphore-ci-bot"
git config --global user.email "ci-bot@semaphore.local"

# 携带凭证克隆GitHub Pages部署分支到临时目录
git clone --branch gh-pages https://${GIT_PUSH_TOKEN}@${SEMAPHORE_GIT_URL#https://} gh-pages-temp

# 清理旧部署文件，复制新构建的静态产物
rm -rf gh-pages-temp/*
cp -r _build/html/* gh-pages-temp/
# 同步.nojekyll等隐藏配置文件，避免GitHub Pages构建异常
cp _build/html/.nojekyll gh-pages-temp/ 2>/dev/null || true

# 提交变更并推送到远程分支
cd gh-pages-temp
git add .
git commit -m "docs: auto update static build [skip ci]"
git push origin gh-pages --force

配置注意事项 #

• 提交信息必须携带[skip ci]标记，避免推送产物分支时重复触发流水线，造成无限循环执行
• 个人访问令牌仅需配置目标仓库的内容读写最小权限，不要开放多余的账号权限，降低安全风险
• 若你的GitHub Pages采用main分支下/docs目录的托管模式，只需调整脚本中的文件复制路径，将产物复制到对应目录后提交推送到main分支即可

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