私有仓库（GitHub App）

通过 GitHub App 部署 GitHub 仓库 —— 一个身份验证，许多仓库。

Application #git#github#app#private#repository

使用你拥有的 GitHub App 部署私有（和公共）GitHub 仓库。在你的组织或选定的仓库上安装应用，将应用凭证粘贴到 Pier，克隆 / 构建 / 部署任何这些仓库而无需每仓库 deploy key。将许多私有仓库部署到一个 Pier 实例的团队的推荐身份验证方法。

使用 Pier 部署

1 打开 Pier 控制台，点击 Add service。
2 从模板列表中选择 Private Repository (GitHub App)。
3 选择版本、设置服务名称，Pier 会自动配置容器、存储和端口。
4 如需 HTTPS，请绑定域名。Traefik 会自动签发 Let's Encrypt 证书。

什么是 GitHub App 模板？

使用你控制的 GitHub App 部署 GitHub 仓库（私有或公共）。你在你的账户或组织下创建应用，在特定仓库上安装它（或组织范围），下载其私钥，并将凭证粘贴到 Pier。Pier 使用 GitHub API 在克隆时请求短寿命安装访问 token —— 无长寿命 PAT，无每仓库 deploy key。

这是将许多私有仓库部署到一个 Pier 实例的团队的推荐身份验证模式。一个应用授权任意数量的仓库；撤销是每安装或每仓库的；审计追踪位于 GitHub 端。

Pier 如何部署它

你提供：

目标仓库的 Git URL (HTTPS)
GitHub App 的 App ID、Installation ID 和私钥 (.pem)
分支 / 标签 / commit、Dockerfile 路径、端口、env vars

在克隆时，Pier 用应用的私钥签名 JWT，从 GitHub API 请求安装访问 token，并使用该 token 通过 HTTPS git clone。token 在约 1 小时内过期，Pier 自动刷新它们。

对于 webhook 驱动的推送部署，配置应用的 webhook URL 以指向服务的 Pier 生成的 webhook URL，设置 webhook secret，Pier 验证并对推送事件作出反应。

何时不要使用本模板

对于个人账户下的 1-5 个私有仓库，更简单的 Deploy Key 模板（每仓库 SSH 密钥）更容易。对于公共仓库，公共仓库模板根本不需要 auth。对于非 GitHub 主机（GitLab、Bitbucket、Gitea 等），使用 Deploy Key。GitHub App 专门是 “带许多 GitHub 私有仓库的团队 / 组织，我们想要一个身份验证表面”的正确答案。

核心功能

一个应用，许多仓库

在你的组织或每仓库上安装 GitHub App。Pier 使用应用的安装 token 克隆任何授权的仓库 —— 无每仓库 deploy key。

组织级或仓库级范围

在整个组织（所有当前和未来仓库）或特定仓库上安装。随时按仓库或按组织撤销。

自动旋转 token

GitHub App 生成短寿命安装访问 token。Pier 自动请求新鲜 token；无需泄漏长寿命的东西。

细粒度权限

应用声明它需要的确切内容（Contents — read）。无访问 Actions、秘密、组织计费或任何其他东西。

包括 Webhook redeploy

GitHub App 可在安装时订阅推送事件。配置一次；推送自动触发 Pier redeploy。

审计追踪

每次克隆在 GitHub 端作为应用安装事件记录 —— 对安全审计有用。

应用场景

带许多私有仓库的组织

你的组织有几十个私有仓库，你不想为每个都有每仓库 deploy key。安装一个 GitHub App，通过 Pier 部署任何仓库。

多语言 monorepo 分解

在一个 Pier 实例上托管来自 N 个单独私有仓库的 N 个服务 —— 全部通过一个应用授权。

产品团队的持续部署

每个团队的仓库在推送到 main 时自动部署，全部通过相同的组织范围应用进行身份验证。

审计感知部署

合规 / 安全团队更喜欢带每仓库范围的单一、审计应用，而不是一堆长寿命 SSH 密钥。

替换 PAT

个人访问 Token 授予绑定到人类账户的仓库范围访问。应用是仓库范围、机器拥有、短寿命 token —— 严格更好。

代码示例

创建 GitHub App text

GitHub → 设置 → Developer settings → GitHub Apps → 新 GitHub App
  名称：pier-deployments
  Homepage URL: https://pier.example.com
  Webhook：（稍后通过 Pier 设置；现在留空）
  权限：
    Contents: Read-only
    Metadata: Read-only
  订阅事件：Push
→ 创建
→ 生成私钥（下载 .pem）
→ 记录 App ID 和 Client ID

在你的组织 / 仓库上安装应用 text

应用设置 → 安装应用 → 选择你的组织
→ 选择："所有仓库" 或 "仅选定仓库"
→ 安装
→ 记录 Installation ID（来自 URL：https://github.com/settings/installations/<ID>）

连接到 Pier text

Pier → 新服务 → 私有仓库（GitHub App）
  Git URL: https://github.com/myorg/myrepo
  分支：main
  App ID: 12345
  Installation ID: 67890
  私钥：（粘贴你下载的 .pem 的内容）
  Dockerfile 路径：/Dockerfile
  端口：3000
→ 部署

设置 webhook 驱动部署 text

Pier 服务 → 设置 → 复制 webhook URL
GitHub App → 设置 → Webhook URL：粘贴它
Webhook secret：（Pier 显示一个复制）
→ 保存
→ 推送到 main → 自动重新构建 + redeploy

对比

vs Deploy Key 模板（本目录）	Deploy Key 对 1-5 个私有仓库更简单。GitHub App 在一个组织下的 10+ 个私有仓库上扩展更好。应用还有审计追踪和短寿命 token。
vs 个人访问 Token (PAT)	PAT 绑定到人类账户并授予对所有他们的仓库的访问。应用范围限定为特定仓库，由你的组织/账户单独拥有。应用严格是更好的安全性。
vs GitLab / Bitbucket / Gitea	本模板特定于 GitHub。对于 GitLab 使用 deploy token；对于 Bitbucket 使用 OAuth 应用；对于 Gitea 使用 deploy key。
vs 公共仓库（本目录）	公共无需任何身份验证 —— 当仓库真正公开时使用。

常见问题

为什么这比 PAT 更好？

PAT 绑定到人类账户、授予广泛访问，并很少过期。GitHub App 安装 token 范围限定为特定仓库、由应用拥有（不是个人）并自动旋转。

私钥在 Pier 中住在哪里？

在 Pier 数据库中加密，在请求时解密以签名 GitHub App API 的 JWT。密钥本身从不离开 Pier。

我可以为多个 Pier 服务使用一个应用吗？

是 —— 那是设计。一个应用授权许多仓库；每仓库创建一个 Pier 服务，全部引用相同的应用凭证。

应用需要什么权限？

Contents — Read-only 和 Metadata — Read-only 足以克隆。订阅 Push 事件用于 webhook redeploy。

webhook 签名如何验证？

Pier 验证你在 GitHub App 上配置的 webhook secret。拒绝任何无有效签名的 webhook。

我可以用本模板部署公共仓库吗？

是 —— 一旦应用已安装，它可以克隆任何授权的仓库，公共或私有。

Token 过期 / 刷新？

安装 token 在约 1 小时内过期。Pier 在每次克隆前从 GitHub API 请求新鲜的。你不管理这个。

在你的 VPS 上部署

部署此服务 →