Python SDK：GitHub 部署

client.apps.deploys 将应用连接到 GitHub，使一次 push 即可完成 deploy。有两种方式：在仓库中添加一个 webhook，或使用 Square Cloud GitHub App。示例使用创建客户端中的 client。app_id 是你的某个应用的 ID：client.account.me() 会列出它们。

Webhook

deploys.set_webhook(app_id, access_token) 使用 GitHub 访问令牌（ghp_... 或 github_pat_...）配置 GitHub webhook deploy，并返回需要添加到仓库中的 webhook URL。

url = client.apps.deploys.set_webhook(app_id, os.environ["GITHUB_TOKEN"])

print(url)  # add it as a webhook in the repository settings

将 "@" 作为令牌传入即可移除 webhook。此时该方法返回 ''。

client.apps.deploys.set_webhook(app_id, "@")

无效的令牌会返回 400 INVALID_ACCESS_TOKEN。

GitHub App

deploys.link_github_app(app_id, repository, branch) 关联一个通过 Square Cloud GitHub App 安装的仓库。它需要 apps:deploy 作用域。

repo = client.apps.deploys.link_github_app(app_id, "octocat/hello-world", "main")

print(repo["id"], repo["full_name"], repo["branch"])

deploys.unlink_github_app(app_id) 移除该关联。要关联其他仓库或分支，请先取消关联。

client.apps.deploys.unlink_github_app(app_id)

关联和取消关联共享 每 60 秒 3 次调用 的限制。

状态	代码	触发条件
400	`GIT_ALREADY_CONFIGURED`	该应用已关联了仓库：请先取消关联
400	`GIT_NOT_CONFIGURED`	在没有任何关联的情况下调用 `unlink_github_app`
400	`BRANCH_NOT_FOUND`, `INVALID_BRANCH_LENGTH`	分支不存在，或其名称超过 256 个字符
403	`GITHUB_NOT_CONNECTED`	你的账户没有安装 GitHub App
403	`REPOSITORY_NOT_AVAILABLE`	该 GitHub App 未通过你的 GitHub 账户安装到该仓库
403	`REPOSITORY_PERMISSION_REQUIRED`	你的 GitHub 账户对该仓库没有写入权限
404	`REPOSITORY_NOT_FOUND`	仓库不存在或不可见
409	`REPOSITORY_BRANCH_ALREADY_CONFIGURED`	另一个应用（任何账户的）已关联了该仓库和分支。仅当该应用属于你时，其 ID 才会出现在 `message` 中
502	`FAILED_TO_FETCH`	GitHub 未确认该分支：可以安全重试

当前配置

deploys.current(app_id) 返回已配置的内容：app 表示 GitHub App 关联，webhook 表示 webhook URL。未设置任何内容时返回 {}。

current = client.apps.deploys.current(app_id)

if "app" in current:
    print(current["app"]["name"], current["app"]["branch"])  # e.g. "octocat/hello-world" "main"
if "webhook" in current:
    print(current["webhook"])

Deploy 历史

deploys.list(app_id) 为每次 deploy 返回一条时间线，每条时间线是一个事件列表，最早的事件在前。只有 Git deploy（webhook 和 GitHub App 的 push）会被记录。

for timeline in client.apps.deploys.list(app_id):
    last = timeline[-1] if timeline else None
    if last is None:
        continue
    print(last["id"], last["state"], last["date"])

    if last["state"] == "error":
        print(last.get("code"), last.get("message"))

字段	说明
`id`	commit SHA
`state`	`pending`、`clone`、`commit`、`restarting`、`success` 或 `error`
`date`	事件发生的时间
`source`	始终为 `"git"`
`branch`	出现在 `clone` 事件中
`files`	出现在 `commit` 事件中：`{ added, removed, modified }`
`code` / `message`	出现在 `error` 事件中：deploy 失败的原因（例如 `CLONE_FAILED`）

后续步骤

网络

分析、DNS、自定义域名和缓存。

部署 API 参考

这些方法背后的 REST 端点。

用 CLI 管理 GitHub 部署

在终端中完成同样的操作。

CLI

VS Code

SDKs

Python SDK：GitHub 部署

Webhook

GitHub App

当前配置

Deploy 历史

后续步骤

网络

部署 API 参考

用 CLI 管理 GitHub 部署

​Webhook

​GitHub App

​当前配置

​Deploy 历史

​后续步骤

网络

部署 API 参考

用 CLI 管理 GitHub 部署

Webhook

GitHub App

当前配置

Deploy 历史

后续步骤