跳到主要内容

GitHub

GitHub 集成可将你的代码仓库连接到 Almirant，以将 pull request 和 commit 关联到工作项，直接从看板查看开发活动，并为 AI 代理提供项目代码上下文。

前置要求​

GitHub 集成由 feature flag 控制。要让它在你的 Almirant 实例中可用，必须启用环境变量 NEXT_PUBLIC_FEATURE_GITHUB。

连接 GitHub​

该连接通过组织级 GitHub OAuth App 安装完成：

  1. 前往 设置 > 集成 > GitHub。
  2. 点击 连接 GitHub。
  3. GitHub 会要求你授权 Almirant 作为 OAuth App。
  4. 选择要安装该应用的组织或账户。
  5. 选择 Almirant 可访问的仓库（全部或选定仓库）。
  6. 确认安装。

完成后，你将在集成设置中看到连接状态和可用仓库。

选定仓库

建议仅授权要与 Almirant 项目关联的仓库，而不是授权全部仓库。之后可从 GitHub 设置中修改权限。

将仓库关联到项目​

连接 GitHub 后，可以将一个或多个仓库关联到每个项目：

  1. 前往要关联仓库的项目。
  2. 前往 仓库 部分。
  3. 点击 关联仓库。
  4. 从可用仓库列表中选择仓库。
  5. 确认关联。

该仓库将关联到项目，其所有活动都会在 Almirant 中可见。

Pull request 和工作项​

该集成最有用的功能之一是 pull request 与工作项之间的自动关联。

如何将 PR 关联到工作项​

在 GitHub 中的 pull request 标题或描述中包含工作项标识符（例如 A-T-42）。Almirant 会检测该引用并自动关联 PR。

PR 标题示例：

feat: Implementar sistema de notificaciones [A-T-42]

PR 描述示例：

## Descripcion
Implementa el sistema de notificaciones push.

Relacionado con: A-T-42

从 Almirant 查看 PR​

在工作项详情中，你可以查看所有关联的 pull request，包括：

  • PR 状态（打开、关闭、已合并）。
  • 作者和创建日期。
  • 指向 GitHub 中 PR 的直接链接。

查看关联的 commit​

除 pull request 外，Almirant 还会显示关联到工作项的 commit，为每项任务关联的代码提供完整可追溯性。

开发活动​

在项目视图中，仓库部分会显示近期开发活动摘要：

  • 主分支上的最新 commit。
  • 打开的 pull request 及其状态。
  • 团队成员在仓库中的活动。

AI 代理的上下文​

当仓库关联到项目时，AI 代理可以访问代码上下文，以便：

  • 在实现新功能时理解项目结构。
  • 在代码审查期间检查现有代码。
  • 基于当前实现生成测试。
  • 基于真实 codebase 知识回答技术问题。

断开 GitHub​

断开 GitHub 集成：

  1. 前往 设置 > 集成 > GitHub。
  2. 点击 断开连接。
  3. 确认断开连接。
注意

断开 GitHub 会移除仓库与项目的关联。工作项会保留 PR 和 commit 的历史引用，但不会再更新新信息。

开发者指南

环境变量​

变量描述必填
NEXT_PUBLIC_FEATURE_GITHUB在 frontend 中启用 GitHub 集成的 feature flag是
GITHUB_CLIENT_IDGitHub OAuth App 的 Client ID是
GITHUB_CLIENT_SECRETGitHub OAuth App 的 Client Secret是

集成架构​

该集成包括：

  • Frontend：frontend/src/domains/github/ 中的 github 域，包含 OAuth 安装和仓库关联的 hooks。
  • Backend：backend/api/src/routes/ 中用于管理安装和仓库的路由。
  • 数据库：schema 中的 githubInstallations 和 repositories 表。
  • Webhooks：接收 GitHub 事件（push、PR）并更新 Almirant 信息的 endpoint。