Integracao com GitHub Actions

O Archyl fornece duas GitHub Actions oficiais que integram a governanca arquitetural diretamente no seu pipeline CI/CD:

Pre-requisitos

Antes de usar as actions, voce precisa de:

1. Uma chave API Archyl — Va em Profile > API Keys e crie uma com escopo de escrita
2. Um Project ID — Encontrado na URL ou pagina de configuracoes do projeto
3. Armazene a chave API como segredo GitHub: Settings > Secrets > Actions > ARCHYL_API_KEY
4. Opcionalmente armazene o ID do projeto como variavel: Settings > Variables > Actions > ARCHYL_PROJECT_ID

Action Conformance Check

Executa suas regras de conformidade em cada pull request e reporta violacoes como comentarios de PR e verificacoes de status de commit.

Configuracao 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. A action coleta todos os arquivos alterados no PR
2. O conteudo dos arquivos e obtido no SHA head
3. Arquivos + conteudos sao enviados para a API do Archyl para avaliacao
4. Todas as regras de conformidade habilitadas sao avaliadas contra os arquivos alterados
5. Um status de commit e publicado (aprovado/reprovado)
6. Um comentario de PR e publicado com detalhes das violacoes
7. O workflow falha se violacoes criticas ou altas forem encontradas

Comentario de PR

Quando violacoes sao encontradas, o Archyl publica um comentario como este:

Archyl Conformance Check — Failed

12 arquivo(s) analisados — 3 violacao(oes) encontrada(s).

Severidade	Quantidade
Critical	1
High	2

O comentario e atualizado em pushes subsequentes — nao cria comentarios duplicados.

Entradas

Saidas

Uso das saidas

Voce pode usar as saidas em etapas subsequentes:

- 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"  # Nao falhar, tratar 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

Analisa arquivos alterados no push para a branch padrao e cria descobertas pendentes para manter seu modelo C4 atualizado.

Configuracao 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  # Obrigatorio 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. A action calcula o diff git entre o commit anterior e o atual
2. O conteudo dos arquivos alterados e obtido no SHA head
3. Os arquivos sao enviados para a API do Archyl para analise de IA
4. Apenas arquivos fonte sao analisados (arquivos de teste, codigo gerado, etc. sao pulados)
5. Novos elementos C4 sao criados como descobertas pendentes para sua revisao
6. Elementos existentes sao automaticamente deduplicados — sem duplicatas
7. Um resumo da etapa e publicado com o status do job de descoberta

Entradas

Saidas

Notas importantes

• fetch-depth: 2 e obrigatorio na etapa de checkout para que o git possa calcular o diff
• A descoberta cria elementos pendentes — eles nao aparecerao no seu modelo C4 ate voce aprova-los
• Apenas arquivos fonte sao analisados (.go, .ts, .py, .java, etc.) — arquivos de config, docs e assets sao pulados
• A action funciona com eventos push e pull_request

Workflow combinado

A configuracao recomendada usa ambas as actions juntas — conformidade em PRs, descoberta em 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 }}

Isso fornece um ciclo completo de governanca arquitetural:

1. Um desenvolvedor abre um PR
2. Regras de conformidade validam as alteracoes contra sua arquitetura
3. Violacoes sao reportadas como comentarios de PR
4. Apos aprovacao e merge, a descoberta incremental atualiza o modelo C4
5. O modelo esta sempre atualizado para a proxima verificacao de PR

Archyl auto-hospedado

Se voce executa o Archyl on-premise, defina a entrada api-url para sua 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

Se voce prefere webhooks a GitHub Actions, pode configurar webhooks push/PR diretamente nas configuracoes do seu projeto. Consulte Webhooks para detalhes.

A abordagem por webhook:

• Nao requer configuracao de GitHub Action
• Usa o token OAuth do proprietario do projeto para acesso a API
• Suporta GitHub e GitLab
• Executa na infraestrutura do Archyl (sem minutos de GitHub Action usados)

A abordagem por GitHub Action:

• Usa sua propria chave API (mais explicito)
• Executa na infraestrutura do GitHub
• Mais facil de personalizar (adicionar condicoes, filtrar caminhos, combinar com outras etapas)
• Funciona com qualquer provedor Git que suporte GitHub Actions