GitHub Actions 集成

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

所有 Actions 均发布在 archyl-com/actions，并以 @v1 进行版本管理。

前提条件

使用 Actions 之前，您需要：

1. Archyl API 密钥 —— 前往 个人资料 > API 密钥 创建一个具有写入范围的密钥
2. 组织 ID —— 可在组织设置页面中找到
3. 项目 ID —— 可在项目的 URL 或设置页面中找到
4. 将它们存储为 GitHub Secret 和变量：

Settings > Secrets > Actions:
  ARCHYL_API_KEY       # Your API key (secret)

Settings > Variables > Actions:
  ARCHYL_ORG_ID        # Organization UUID
  ARCHYL_PROJECT_ID    # Project UUID

快速开始

最快的上手方式是使用 Archyl 的可复用工作流：一个用于 PR，一个用于推送到 main 分支：

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

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

jobs:
  # Conformance check + drift score on PRs (run in parallel)
  pr-checks:
    if: github.event_name == 'pull_request'
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

  # Generate context + sync + release on merge to main
  main-sync:
    if: github.event_name == 'push'
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      sync: true
      release: true
      release-environment: 'production'
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

这为您提供了完整的架构治理闭环：合规规则验证每个 PR，漂移评分跟踪代码与模型的吻合程度，合并后模型会自动保持同步。

单个 Actions

Conformance Check

针对拉取请求中变更的文件运行您的合规规则。违规会以内联注释标出，并在 PR 中发布摘要评论。

- uses: archyl-com/actions/conformance-check@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

输入

输出

使用输出

- uses: archyl-com/actions/conformance-check@v1
  id: conformance
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    fail-on: none  # Don't fail, handle manually

- name: Custom handling
  if: steps.conformance.outputs.status == 'fail'
  run: |
    echo "Found ${{ steps.conformance.outputs.total-violations }} violations"
    echo "Errors: ${{ steps.conformance.outputs.errors }}"
    echo "Warnings: ${{ steps.conformance.outputs.warnings }}"

Drift Score

计算架构漂移评分，即您的代码库与 C4 模型的吻合程度。还可以选择执行质量门禁：当评分低于阈值时使构建失败。

- uses: archyl-com/actions/drift-score@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    threshold: 70

输入

输出

Generate Context

生成包含您架构上下文的 archyl.txt 文件，针对 AI Agent 和 LLM 进行了优化。文件发生变化时可自动提交。

- uses: archyl-com/actions/generate-context@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    commit: 'true'

输入

输出

Auto CR

代码合并到 main 时，自动在 Archyl 中创建架构变更请求。它会分析 diff，识别与架构相关的变更，并跟踪这些变更以供评审。

- uses: archyl-com/actions/auto-cr@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    organization-id: ${{ vars.ARCHYL_ORG_ID }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

输入

输出

Release

从您的 CI 管道在 Archyl 中创建或更新发布。跟踪部署，将其与环境和 C4 元素关联，并为您的 DORA 指标提供数据。

- uses: archyl-com/actions/release@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}
    status: deployed
    environment: production

输入

输出

Sync

将您的 archyl.yaml DSL 文件同步到 Archyl。以代码形式声明您的架构，并在每次提交时推送变更。

- uses: archyl-com/actions/sync@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: ${{ vars.ARCHYL_PROJECT_ID }}

输入

输出

可复用工作流

Archyl 提供两个可复用工作流，将多个 Actions 组合起来，覆盖常见场景。

archyl-pr.yml

在每个拉取请求上并行运行合规检查和漂移评分。

jobs:
  archyl:
    uses: archyl-com/actions/.github/workflows/archyl-pr.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      drift-threshold: 70        # Fail if drift score drops below 70
      fail-on: error              # Fail on error-level conformance violations
      comment-on-pr: true         # Post PR comments with results
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

除 organization-id、project-id 和 api-key 外，所有输入均为可选。

archyl-main.yml

推送到 main 时运行 generate-context、sync 和 release。每个任务都可以单独开启或关闭。

jobs:
  archyl:
    uses: archyl-com/actions/.github/workflows/archyl-main.yml@v1
    with:
      organization-id: ${{ vars.ARCHYL_ORG_ID }}
      project-id: ${{ vars.ARCHYL_PROJECT_ID }}
      generate-context: true       # Generate and auto-commit archyl.txt
      context-format: markdown     # LLM-optimized format
      sync: true                   # Sync archyl.yaml to Archyl
      sync-file: archyl.yaml       # Path to your archyl.yaml
      release: true                # Create a release record
      release-status: deployed
      release-environment: production
    secrets:
      api-key: ${{ secrets.ARCHYL_API_KEY }}

其他 CI 平台

GitLab CI

Archyl 为 GitLab 提供了一个可引入的 CI 模板。它会在合并请求上运行合规检查和漂移评分，并在推送到默认分支时生成上下文。

设置：

1. 在 Settings > CI/CD > Variables 中添加所需的 CI/CD 变量：

   • ARCHYL_API_KEY（masked、protected）
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. 在您的 .gitlab-ci.yml 中引入该模板：

include:
  - remote: 'https://raw.githubusercontent.com/archyl-com/actions/main/ci-templates/gitlab/.archyl-ci.yml'

这会向您的管道添加三个任务：

• archyl:conformance —— 在合并请求上运行
• archyl:drift-score —— 在合并请求上运行
• archyl:generate-context —— 在推送到默认分支时运行

可选变量：ARCHYL_API_URL、ARCHYL_DRIFT_THRESHOLD。

Bitbucket Pipelines

将 Archyl 管道模板复制到您的 bitbucket-pipelines.yml 中。

设置：

1. 在 Settings > Repository variables 中添加所需的代码仓库变量：

   • ARCHYL_API_KEY（secured）
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. 添加管道步骤：

pipelines:
  pull-requests:
    '**':
      - step:
          name: "Archyl Conformance Check"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq git
            - # ... conformance check script
      - step:
          name: "Archyl Drift Score"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq
            - # ... drift score script

  branches:
    main:
      - step:
          name: "Archyl Generate Context"
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq git
            - # ... generate context script

完整模板位于 archyl-com/actions/ci-templates/bitbucket/archyl-pipelines.yml。

组合示例

一个同时使用全部六个 Actions 的完整工作流：

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

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

jobs:
  # --- PR checks (parallel) ---

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

  drift:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          threshold: 70
          comment-on-pr: 'true'

  # --- Main branch (after merge) ---

  generate-context:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/generate-context@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          commit: 'true'

  sync:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  auto-cr:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: archyl-com/actions/auto-cr@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ vars.ARCHYL_ORG_ID }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

  release:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/release@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}
          status: deployed
          environment: production
          source-url: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}

查看结果

所有由 CI 触发的检查结果都会显示在 Archyl 中：

• 合规检查 —— 显示在合规仪表板中（代理中心 > 仪表板 选项卡）。点击任一检查即可查看按文件分组的违规。
• 漂移评分 —— 显示在项目的漂移部分。可跟踪评分随时间变化的历史。
• 变更请求 —— 显示在请求部分。在接受架构变更之前先进行评审。
• 发布 —— 显示在发布部分和环境页面。为您的 DORA 指标提供数据。
• 同步结果 —— 立即反映在您的 C4 模型中。

有关合规仪表板的更多详情，请参阅合规规则。

自托管 Archyl

如果您在本地部署 Archyl，请在任一 Action 上设置 api-url 输入，使其指向您的实例：

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

所有 Actions 的默认值均为 https://api.archyl.com。