通过 GitHub Actions、Webhook 和 REST API 的自动摄取，跨架构跟踪部署

发布管理

发布管理将部署作为架构工作区中的一等对象进行跟踪。每个发布都关联到一个 C4 元素，为您的图表提供实际运行内容的实时视图。

核心概念

发布

发布代表部署到某个环境的特定版本。每个发布包含：

字段	描述
版本	语义版本标签或标识符（如 `v2.4.0`、`3.12.0-rc.2`）
状态	部署生命周期中的当前状态
环境	目标环境（生产、预发布等）
变更日志	此次发布的变更内容
来源	发布创建方式（手动、API、GitHub Action、Webhook）
关联元素	此发布所属的系统或容器

环境

环境代表部署目标。它们由用户定义并带有颜色编码。

常见设置包括：

开发 → 预发布 → 生产
Dev → QA → Pre-prod → Production

根据工作流需要创建任意数量的环境。每个发布都标记其目标环境。

状态生命周期

发布经历以下状态：

状态	描述
已计划	发布已存在但尚未部署。用于跟踪即将到来的版本。
进行中	部署正在进行中。由 CI/CD 集成自动设置。
已部署	发布已在目标环境中上线。
失败	部署未成功。条目保留作为尝试的记录。
已回滚	发布已部署但随后被回退。

设置发布跟踪

1. 创建环境

前往项目的设置
打开发布选项卡
在环境下，点击 添加环境
输入名称并选择颜色
拖动按部署阶段重新排序环境

2. 配置默认关联目标

设置发布应默认附加到的系统和可选容器：

在发布设置选项卡中，找到 默认关联目标
从下拉菜单中选择系统
可选择该系统中的容器
当摄取的发布未指定元素时使用此目标

3. 选择集成方式

Archyl 支持三种自动摄取发布的方式。

集成方式

GitHub Actions

将 Archyl 官方 GitHub Action 添加到您的部署工作流。

最小设置：

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}

完整配置：

- uses: archyl/release-action@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    version: ${{ github.ref_name }}
    environment: production
    system-id: <your-system-uuid>
    container-id: <your-container-uuid>
    changelog: "Bug fixes and performance improvements"
    status: deployed

该 Action 在每次成功部署时将版本、提交 SHA、环境和变更日志发送到 Archyl。

Webhook

配置 Webhook 摄取以接收来自 GitHub 或 GitLab 的发布事件。

在发布设置选项卡中，启用 Webhook
复制显示的 Webhook URL
在 GitHub 或 GitLab 中，添加指向该 URL 的新 Webhook
选择 Release 或 Tag push 事件类型

配置选项：

设置	描述
标签模式	过滤哪些标签创建发布（如 `v*` 用于以 `v` 开头的标签）
默认环境	分配给 Webhook 创建的发布的环境
Webhook 密钥	用于负载验证的共享密钥

当新发布被发布或匹配的标签被推送时，Archyl 自动创建发布条目。

REST API

适用于任何能发起 HTTP 请求的 CI/CD 工具——Jenkins、CircleCI、Bitbucket Pipelines 或自定义流水线。

端点： POST /api/v1/projects/:projectId/releases

头：

Authorization: Bearer <api-key>
Content-Type: application/json

负载：

{
  "version": "v2.4.0",
  "status": "deployed",
  "changelog": "Added payment retry logic",
  "environmentId": "<environment-uuid>",
  "systemId": "<system-uuid>",
  "containerId": "<container-uuid>",
  "sourceUrl": "https://github.com/org/repo/releases/tag/v2.4.0"
}

设置选项卡显示可复制的代码片段，自动填充 API 密钥和元素 ID。

视图

发布时间线

主视图。发布按月份反向时间顺序分组。每个条目显示：

版本标签
状态指示器
环境标签（带颜色编码）
关联的系统或容器
来源（GitHub Action、Webhook、API、手动）
相对时间戳

点击任何发布打开详情面板，包含完整的变更日志、日期和来源链接。

过滤：

按环境（如仅显示生产部署）
按状态（如仅显示失败的部署）
按关联元素

部署矩阵

适合管理多个服务跨多个环境的团队的网格视图。

行 — 系统和容器
列 — 环境
单元格 — 该组合的最新部署发布

矩阵使环境漂移一目了然。当预发布和生产版本出现分歧时，您会立即发现。

将发布关联到架构

每个发布都可以关联到系统、容器或两者。

自动关联

使用 GitHub Actions 或 Webhook 时，发布关联到设置中配置的默认目标。您可以通过指定 system-id 和 container-id 为每个发布覆盖目标。

手动关联

通过 UI 创建发布时：

点击 新建发布
填写版本、状态和变更日志
选择目标系统和/或容器
选择环境
点击创建

在图表上查看

右键点击 C4 图表上的任何元素打开其详情面板。关联的发布出现在发布部分，与关系、ADR 和 API 契约并列。元素显示其最新发布版本和环境。

手动创建发布

不是每个发布都来自流水线。手动创建发布：

导航到发布选项卡
点击 新建发布
输入版本，选择状态和环境
编写变更日志（支持 Markdown）
关联到系统和/或容器
点击创建

手动发布在时间线中来源标记为手动。

最佳实践

使用语义版本

使用语义版本标记发布（如 v1.2.3）
非生产发布包含预发布标识符（如 v2.0.0-rc.1）
跨环境保持版本字符串一致

跟踪所有环境

为每个部署阶段创建环境
不要跳过预发布——部署矩阵在显示完整流水线时最有用
使用矩阵视图尽早发现环境漂移

自动化摄取

使用 GitHub Actions 或 Webhook 而非手动输入
一次设置集成，之后每次部署自动流入
为热修复或特殊部署保留手动创建

编写变更日志

每次发布包含有意义的变更日志
总结变更了什么以及为什么
尽可能链接到相关的问题或 Pull Request

关联到正确的层次

部署整个应用时关联到系统
部署系统中的单个服务时关联到容器
保持一致——选择一个约定并坚持

后续步骤

API 契约 — 记录您的 API 规范
架构洞察 — 检测架构问题
架构变更请求 — 通过审查工作流提出变更

发布管理 - Archyl Docs