Integracion con GitHub Actions

Archyl proporciona dos GitHub Actions oficiales que integran la gobernanza arquitectonica directamente en tu pipeline CI/CD:

Requisitos previos

Antes de usar las actions, necesitas:

1. Una clave API de Archyl — Ve a Profile > API Keys y crea una con scope de escritura
2. Un Project ID — Disponible en la URL o pagina de configuracion de tu proyecto
3. Almacena la clave API como secreto de GitHub: Settings > Secrets > Actions > ARCHYL_API_KEY
4. Opcionalmente almacena el ID del proyecto como variable: Settings > Variables > Actions > ARCHYL_PROJECT_ID

Action Conformance Check

Ejecuta tus reglas de conformidad en cada pull request y reporta violaciones como comentarios de PR y estados de commit.

Configuracion rapida

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

Como funciona

1. La action recopila todos los archivos modificados en el PR
2. El contenido de los archivos se obtiene en el SHA head
3. Archivos + contenidos se envian a la API de Archyl para evaluacion
4. Todas las reglas de conformidad habilitadas se evaluan contra los archivos modificados
5. Se publica un estado de commit (aprobado/fallido)
6. Se publica un comentario de PR con detalles de violaciones
7. El workflow falla si se encuentran violaciones criticas o altas

Comentario de PR

Cuando se encuentran violaciones, Archyl publica un comentario como este:

Archyl Conformance Check — Failed

12 archivo(s) analizados — 3 violacion(es) encontradas.

Severidad	Cantidad
Critical	1
High	2

El comentario se actualiza en pushes posteriores — no crea comentarios duplicados.

Entradas

Salidas

Uso de salidas

Puedes usar las salidas en pasos posteriores:

- 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"  # No fallar, manejar manualmente

- 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 }}"

Action Incremental Discovery

Analiza archivos modificados en push a la rama por defecto y crea descubrimientos pendientes para mantener tu modelo C4 actualizado.

Configuracion rapida

# .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  # Requerido para git diff
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Como funciona

1. La action calcula el diff git entre el commit anterior y el actual
2. El contenido de los archivos modificados se obtiene en el SHA head
3. Los archivos se envian a la API de Archyl para analisis IA
4. Solo se analizan archivos fuente (archivos de test, codigo generado, etc. se omiten)
5. Nuevos elementos C4 se crean como descubrimientos pendientes para tu revision
6. Los elementos existentes se deduplican automaticamente — sin duplicados
7. Se publica un resumen de paso con el estado del job de descubrimiento

Entradas

Salidas

Notas importantes

• fetch-depth: 2 es requerido en el paso de checkout para que git pueda calcular el diff
• El descubrimiento crea elementos pendientes — no apareceran en tu modelo C4 hasta que los apruebes
• Solo se analizan archivos fuente (.go, .ts, .py, .java, etc.) — archivos de config, docs y assets se omiten
• La action funciona con eventos push y pull_request

Workflow combinado

La configuracion recomendada usa ambas actions juntas — conformidad en PRs, descubrimiento en merges:

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

Esto te da un ciclo completo de gobernanza arquitectonica:

1. Un desarrollador abre un PR
2. Las reglas de conformidad validan los cambios contra tu arquitectura
3. Las violaciones se reportan como comentarios de PR
4. Una vez aprobado y fusionado, el descubrimiento incremental actualiza el modelo C4
5. El modelo siempre esta actualizado para la proxima verificacion de PR

Archyl auto-alojado

Si ejecutas Archyl on-premise, configura la entrada api-url a tu instancia:

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

Alternativa por Webhook

Si prefieres webhooks sobre GitHub Actions, puedes configurar webhooks push/PR directamente en la configuracion de tu proyecto. Consulta Webhooks para mas detalles.

El enfoque webhook:

• No requiere configuracion de GitHub Action
• Usa el token OAuth del propietario del proyecto para acceso a la API
• Soporta GitHub y GitLab
• Se ejecuta en la infraestructura de Archyl (sin minutos de GitHub Action usados)

El enfoque GitHub Action:

• Usa tu propia clave API (mas explicito)
• Se ejecuta en la infraestructura de GitHub
• Mas facil de personalizar (agregar condiciones, filtrar rutas, combinar con otros pasos)
• Funciona con cualquier proveedor Git que soporte GitHub Actions