Integración con GitHub Actions

Archyl proporciona seis GitHub Actions oficiales que integran la gobernanza arquitectónica directamente en tu pipeline de CI/CD.

Todas las actions están publicadas en archyl-com/actions y versionadas con @v1.

Requisitos previos

Antes de usar las actions, necesitas:

1. Una clave API de Archyl — Ve a Perfil > Claves API y crea una con scope de escritura
2. Un ID de organización — Lo encontrarás en la página de configuración de tu organización
3. Un ID de proyecto — Lo encontrarás en la URL o en la página de configuración de tu proyecto
4. Guárdalos como secretos y variables de GitHub:

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

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

Inicio rápido

La forma más rápida de empezar es usar los workflows reutilizables de Archyl — uno para los PR y otro para los push a la rama 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 }}

Esto te da un ciclo completo de gobernanza arquitectónica: las reglas de conformidad validan cada PR, la puntuación de deriva mide hasta qué punto tu código coincide con el modelo y, al hacer merge, el modelo se mantiene sincronizado automáticamente.

Actions individuales

Conformance Check

Ejecuta tus reglas de conformidad sobre los archivos modificados en un pull request. Anota las violaciones en línea y publica un comentario de resumen en el 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 }}

Entradas

Salidas

Uso de las salidas

- 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

Calcula la puntuación de deriva arquitectónica — hasta qué punto tu código base coincide con tu modelo C4. Opcionalmente, aplica un quality gate haciendo fallar el build si la puntuación cae por debajo de un umbral.

- 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

Entradas

Salidas

Generate Context

Genera un archivo archyl.txt con tu contexto arquitectónico, optimizado para agentes de IA y LLM. Puede hacer commit automático del archivo cuando cambia.

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

Entradas

Salidas

Auto CR

Crea automáticamente una solicitud de cambio de arquitectura en Archyl cuando se hace merge de código en main. Analiza el diff para detectar los cambios relevantes para la arquitectura y los registra para su revisión.

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

Entradas

Salidas

Release

Crea o actualiza una release en Archyl desde tu pipeline de CI. Registra los despliegues, asócialos a entornos y elementos C4, y alimenta tus métricas DORA.

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

Entradas

Salidas

Sync

Sincroniza tu archivo DSL archyl.yaml con Archyl. Declara tu arquitectura como código y envía los cambios en cada commit.

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

Entradas

Salidas

Workflows reutilizables

Archyl ofrece dos workflows reutilizables que combinan varias actions para los escenarios más habituales.

archyl-pr.yml

Ejecuta la verificación de conformidad y la puntuación de deriva en paralelo en cada pull request.

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

Todas las entradas son opcionales excepto organization-id, project-id y api-key.

archyl-main.yml

Ejecuta generate-context, sync y release en cada push a main. Cada job se puede activar o desactivar de forma independiente.

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

Otras plataformas de CI

GitLab CI

Archyl ofrece una plantilla de CI incluible para GitLab. Ejecuta la verificación de conformidad y la puntuación de deriva en los merge requests, y genera el contexto en los push a la rama por defecto.

Configuración:

1. Añade las variables de CI/CD necesarias en Settings > CI/CD > Variables:

   • ARCHYL_API_KEY (enmascarada, protegida)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Incluye la plantilla en tu .gitlab-ci.yml:

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

Esto añade tres jobs a tu pipeline:

• archyl:conformance — se ejecuta en los merge requests
• archyl:drift-score — se ejecuta en los merge requests
• archyl:generate-context — se ejecuta en los push a la rama por defecto

Variables opcionales: ARCHYL_API_URL, ARCHYL_DRIFT_THRESHOLD.

Bitbucket Pipelines

Copia la plantilla de pipelines de Archyl en tu bitbucket-pipelines.yml.

Configuración:

1. Añade las variables de repositorio necesarias en Settings > Repository variables:

   • ARCHYL_API_KEY (segura)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Añade los pasos del pipeline:

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

La plantilla completa está disponible en archyl-com/actions/ci-templates/bitbucket/archyl-pipelines.yml.

Ejemplo combinado

Un workflow completo que usa las seis actions juntas:

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

Ver los resultados

Los resultados de todas las verificaciones lanzadas desde CI aparecen en Archyl:

• Verificaciones de conformidad — visibles en el panel de conformidad (pestaña Hub de Agentes > Panel). Haz clic en cualquier verificación para ver las violaciones agrupadas por archivo.
• Puntuaciones de deriva — visibles en la sección de deriva de tu proyecto. Sigue la evolución de la puntuación a lo largo del tiempo.
• Solicitudes de cambio — visibles en la sección Solicitudes. Revisa los cambios de arquitectura antes de aceptarlos.
• Releases — visibles en la sección Releases y en la página Entornos. Alimentan tus métricas DORA.
• Resultados de la sincronización — se reflejan de inmediato en tu modelo C4.

Consulta Reglas de conformidad para más detalles sobre el panel de conformidad.

Archyl auto-alojado

Si ejecutas Archyl on-premise, define la entrada api-url en cualquier action para que apunte a tu instancia:

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

El valor por defecto es https://api.archyl.com para todas las actions.