mkdocs部署GitHub Pages时github-actions[bot]403权限报错解决

部署时返回github-actions[bot]权限拒绝，本质是工作流拿到的认证身份没有目标仓库的写入权限，按以下顺序排查：

• 核对个人访问令牌（PAT）有效性：你存在Secrets里的PAT，生成时必须勾选完整的repo权限范围，先到个人开发者设置页确认令牌没有过期、权限范围没有缺项。如果是部署到私有仓库，不要选仅公开仓库权限的PAT。
• 修正工作流权限配置：如果用GitHub自带的GITHUB_TOKEN做认证，必须在工作流的job层级加如下权限声明，默认配置下该令牌没有仓库写入权限：

permissions:
  contents: write
  pages: write
  id-token: write

如果你坚持用自己存在Secrets里的PAT做认证，要确认部署步骤里的远程仓库地址已经拼接了PAT认证信息，格式为https://<你的PAT值>@github.com/用户名/仓库名.git，如果没拼接这部分，工作流会默认用无写入权限的github-actions[bot]身份发起请求，直接报403。

• 核对仓库Pages配置：到仓库设置的Pages页面，把构建源切换为GitHub Actions，不要使用旧版的「从分支部署」选项。同时检查gh-pages分支是否配置了分支保护规则，如果开了强制PR审核、限制推送用户名单的规则，要么把工作流使用的认证账号加进白名单，要么临时关闭规则测试部署。
• 核对Secrets配置范围：确认你配置的PAT是存在当前仓库的Actions Secrets条目下，不要错存到个人账号Secrets、或者指定环境的环境Secrets里——如果存到环境Secrets，必须在工作流的job里声明对应环境，否则工作流读不到Secret值，会fallback到默认的bot身份。

手动触发工作流时出现该报错，属于运行环境或依赖兼容问题，按以下顺序排查：

• 更换运行器镜像：检查工作流里的runs-on配置，不要使用已经下线的旧版镜像比如ubuntu-18.04，直接替换为ubuntu-latest即可。如果使用自托管运行器，要确认运行器的Python版本不低于3.8，git版本为2.30以上，满足mkdocs运行的基础要求。
• 替换过时的第三方Action：不要用长期不更新的第三方mkdocs部署Action，优先使用GitHub官方提供的Pages工作流组件组合完成构建部署，避免第三方Action的兼容问题。
• 清空失效缓存：如果你在工作流里配置了pip依赖缓存，直接到仓库Actions的缓存管理页，删除所有和pip、mkdocs相关的旧缓存，旧缓存和新运行器系统版本不兼容是触发这个报错的最常见原因，清缓存后重新触发工作流即可。
• 修正依赖版本：检查你的mkdocs依赖配置文件，不要锁死过老的mkdocs、主题或插件版本，老版本依赖无法兼容新运行器的系统依赖，会触发发行版无效的错误，可以先放开版本限制安装最新版依赖测试跑通，再按需锁定兼容的版本号。

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