GitHub Actions 集成

Archyl 提供两个官方 GitHub Actions，将架构治理直接集成到您的 CI/CD 管道中：

前提条件

使用 Actions 之前，您需要：

1. Archyl API 密钥 — 前往 Profile > API Keys 创建一个具有写入范围的密钥
2. Project ID — 在项目的 URL 或设置页面中找到
3. 将 API 密钥存储为 GitHub Secret: Settings > Secrets > Actions > ARCHYL_API_KEY
4. 可选地将项目 ID 存储为变量: Settings > Variables > Actions > ARCHYL_PROJECT_ID

Conformance Check Action

在每个拉取请求上运行合规规则，并以 PR 评论和提交状态检查的形式报告违规。

快速设置

# .github/workflows/archyl-conformance.yml
name: Architecture Conformance

on:
  pull_request:
    branches: [main]

jobs:
  conformance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl/archyl/.github/actions/conformance-check@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

工作原理

1. Action 收集 PR 中所有变更的文件
2. 在 head SHA 获取文件内容
3. 文件和内容被发送到 Archyl API 进行评估
4. 所有已启用的合规规则针对变更文件进行评估
5. 发布提交状态（通过/失败）
6. 发布包含违规详情的 PR 评论
7. 如果发现 Critical 或 High 违规，工作流失败

PR 评论

当发现违规时，Archyl 发布如下评论：

Archyl Conformance Check — Failed

分析了 12 个文件 — 发现 3 个违规。

严重级别	数量
Critical	1
High	2

评论在后续推送时更新 — 不会创建重复评论。

输入

输出

使用输出

您可以在后续步骤中使用输出：

- uses: archyl/archyl/.github/actions/conformance-check@main
  id: archyl
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    fail-on-violations: "false"  # 不失败，手动处理

- name: Custom handling
  if: steps.archyl.outputs.passed == 'false'
  run: |
    echo "Found ${{ steps.archyl.outputs.violations }} violations"
    echo "Critical: ${{ steps.archyl.outputs.critical }}"
    echo "High: ${{ steps.archyl.outputs.high }}"

Incremental Discovery Action

在推送到默认分支时分析变更的文件，并创建待处理的发现以保持 C4 模型的最新状态。

快速设置

# .github/workflows/archyl-discovery.yml
name: Architecture Sync

on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # git diff 所需
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

工作原理

1. Action 计算上一个提交和当前提交之间的 git diff
2. 在 head SHA 获取变更文件的内容
3. 文件被发送到 Archyl API 进行 AI 分析
4. 仅分析源文件（跳过测试文件、生成的代码等）
5. 新的 C4 元素作为待处理的发现创建，供您审查
6. 现有元素自动去重 — 无重复
7. 发布包含发现任务状态的步骤摘要

输入

输出

重要说明

• checkout 步骤中需要 fetch-depth: 2（以便 git 可以计算 diff）
• 发现创建的是待处理元素 — 在您批准之前不会出现在 C4 模型中
• 仅分析源文件（.go、.ts、.py、.java 等） — 配置文件、文档和资源文件会被跳过
• Action 支持 push 和 pull_request 事件

组合工作流

推荐的设置同时使用两个 Actions — PR 上进行合规检查，合并时进行发现：

# .github/workflows/archyl.yml
name: Archyl Architecture

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  conformance:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl/archyl/.github/actions/conformance-check@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  discovery:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

这为您提供了完整的架构治理循环：

1. 开发者打开 PR
2. 合规规则验证变更是否符合架构
3. 违规以 PR 评论形式报告
4. 批准并合并后，增量发现更新 C4 模型
5. 模型始终保持最新，为下一次 PR 检查做好准备

自托管 Archyl

如果您在本地运行 Archyl，请将 api-url 输入设置为您的实例：

- uses: archyl/archyl/.github/actions/conformance-check@main
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    api-url: "https://archyl.internal.company.com/api/v1"

Webhook 替代方案

如果您更喜欢 Webhook 而非 GitHub Actions，可以直接在项目设置中配置 push/PR Webhook。详情请参阅 Webhooks。

Webhook 方式：

• 无需 GitHub Action 配置
• 使用项目所有者的 OAuth 令牌进行 API 访问
• 支持 GitHub 和 GitLab
• 在 Archyl 的基础设施上运行（不消耗 GitHub Action 分钟数）

GitHub Action 方式：

• 使用您自己的 API 密钥（更明确）
• 在 GitHub 的基础设施上运行
• 更容易自定义（添加条件、过滤路径、与其他步骤组合）
• 适用于支持 GitHub Actions 的任何 Git 提供商