GitHub Actions 통합

Archyl은 아키텍처 거버넌스를 CI/CD 파이프라인에 직접 통합하는 여섯 가지 공식 GitHub Actions를 제공합니다.

모든 Action은 archyl-com/actions에 게시되며 @v1로 버전이 관리됩니다.

사전 요구사항

Actions를 사용하기 전에 다음이 필요합니다:

1. Archyl API 키 — 프로필 > API 키에서 쓰기 범위의 키를 생성합니다
2. 조직 ID — 조직 설정 페이지에서 확인할 수 있습니다
3. 프로젝트 ID — 프로젝트 URL 또는 설정 페이지에서 확인할 수 있습니다
4. 이 값들을 GitHub 시크릿과 변수로 저장합니다:

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

AI 에이전트와 LLM에 최적화된 아키텍처 컨텍스트를 담은 archyl.txt 파일을 생성합니다. 파일이 변경되면 자동으로 커밋할 수 있습니다.

- 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은 자주 쓰는 시나리오에 맞춰 여러 Action을 묶은 두 가지 재사용 가능한 워크플로우를 제공합니다.

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를 실행합니다. 각 job은 개별적으로 켜고 끌 수 있습니다.

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에서 include해 쓸 수 있는 CI 템플릿을 제공합니다. 머지 리퀘스트에서는 적합성 검사와 드리프트 점수를 실행하고, 기본 브랜치로 푸시할 때는 컨텍스트를 생성합니다.

설정:

1. Settings > CI/CD > Variables에서 필요한 CI/CD 변수를 추가합니다:

   • ARCHYL_API_KEY (masked, protected로 설정)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. .gitlab-ci.yml에 템플릿을 include합니다:

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

이렇게 하면 파이프라인에 세 개의 job이 추가됩니다:

• 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에서 확인할 수 있습니다.

결합 예제

여섯 가지 Action을 모두 함께 사용하는 전체 워크플로우입니다:

# .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"

모든 Action의 기본값은 https://api.archyl.com입니다.