GitHub Actions 통합

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

사전 요구사항

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

1. Archyl API 키 — Profile > API Keys에서 쓰기 범위의 키를 생성
2. Project ID — 프로젝트 URL 또는 설정 페이지에서 확인
3. API 키를 GitHub 시크릿으로 저장: 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. 파일이 AI 분석을 위해 Archyl API로 전송됨
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 대안

GitHub Actions보다 Webhook을 선호하는 경우, 프로젝트 설정에서 직접 push/PR Webhook을 구성할 수 있습니다. 자세한 내용은 Webhooks를 참조하세요.

Webhook 접근 방식:

• GitHub Action 구성이 필요 없음
• API 접근에 프로젝트 소유자의 OAuth 토큰 사용
• GitHub 및 GitLab 지원
• Archyl의 인프라에서 실행 (GitHub Action 시간 소모 없음)

GitHub Action 접근 방식:

• 자체 API 키 사용 (더 명시적)
• GitHub의 인프라에서 실행
• 더 쉬운 커스터마이징 (조건 추가, 경로 필터링, 다른 단계와 결합)
• GitHub Actions를 지원하는 모든 Git 제공업체에서 작동