如何在GitHub API中使用GitHub Apps生成的ghs_*类型访问令牌？

核心踩坑原因 #

之前网上流传的示例里用curl -u 传令牌的写法有个容易忽略的前提：curl的-u是专门用来做HTTP Basic Auth的参数，必须按照用户名:凭证的格式传值。很多新手直接把完整的访问令牌塞给-u，会被curl识别成“没带密码的用户名”，根本生成不了合法的鉴权头，请求自然会一直401失败。

正确的调用规范 #

这类ghs_开头的GitHub App安装访问令牌，和普通个人访问令牌的鉴权逻辑完全一致，不需要走Basic Auth传参，直接通过标准Bearer鉴权头传递即可：

• 必须携带的请求头：
  • Accept: application/vnd.github.everest-preview+json （兼容老的接口预览格式，目前该触发工作流的接口已正式上线，保留该头不会引发兼容问题）
  • Authorization: Bearer <你的ghs_开头的安装访问令牌>
• 修正后可直接运行的curl示例：

curl -X POST https://api.github.com/repos/{{用户名}}/{{仓库名}}/dispatches \
  -H "Accept: application/vnd.github.everest-preview+json" \
  -H "Authorization: Bearer ghs_tVGHE4l5i4kjhasslirerno666222" \
  --data '{
    "event_type": "custom-trigger-event",
    "client_payload": {
      "自定义业务参数": "参数值"
    }
  }'

调用时需要提前确认的常见排障点 #

• 确认你的GitHub App在对应仓库的安装配置中，已开启Contents: read and write权限，触发仓库dispatches事件必须匹配这个权限范围，权限缺失会直接返回403错误。
• 确认请求路径里的用户名、仓库名，是你的App实际被授权访问的仓库范围，未被授权的仓库哪怕令牌格式正确也会返回404。
• GitHub App的安装访问令牌默认有效期仅为1小时，不要将获取到的令牌硬编码到长期运行的逻辑中，临期时需要重新通过应用JWT申请新的安装令牌。
• 如果你习惯使用Basic Auth的写法，也可以按照-u x-access-token:<你的ghs_令牌值>的格式传参，GitHub API是兼容这种写法的，但相比直接写Bearer鉴权头，这种写法更容易因格式写错引发鉴权失败。

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