Integração com GitHub Actions

O Archyl oferece seis GitHub Actions oficiais que integram a governança arquitetural diretamente no seu pipeline de CI/CD.

Todas as actions são publicadas em archyl-com/actions e versionadas com @v1.

Pré-requisitos

Antes de usar as actions, você precisa de:

1. Uma chave de API do Archyl -- Vá em Perfil > Chaves de API e crie uma com escopo de escrita
2. Um ID da organização -- Encontrado na página de configurações da sua organização
3. Um ID do projeto -- Encontrado na URL ou na página de configurações do seu projeto
4. Armazene esses valores como secrets e variáveis do GitHub:

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

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

Início Rápido

A forma mais rápida de começar é usar os workflows reutilizáveis do Archyl -- um para PRs e outro para pushes na branch 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 }}

Isso fornece um ciclo completo de governança arquitetural: as regras de conformidade validam cada PR, a pontuação de desvio acompanha o quanto seu código corresponde ao modelo e, no merge, o modelo se mantém sincronizado automaticamente.

Actions Individuais

Conformance Check

Executa suas regras de conformidade nos arquivos alterados em um pull request. Anota as violações diretamente nas linhas e publica um comentário de resumo no 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

Saídas

Uso das Saídas

- 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 a pontuação de desvio arquitetural -- o quanto sua base de código corresponde ao seu modelo C4. Opcionalmente, aplica um quality gate fazendo o build falhar se a pontuação cair abaixo de um limite.

- 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

Saídas

Generate Context

Gera um arquivo archyl.txt com o contexto da sua arquitetura, otimizado para agentes de IA e LLMs. Pode fazer commit automático do arquivo quando ele muda.

- 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

Saídas

Auto CR

Cria automaticamente uma solicitação de mudança de arquitetura no Archyl quando o código é mesclado na main. Analisa o diff para detectar alterações relevantes para a arquitetura e as registra para revisão.

- 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

Saídas

Release

Cria ou atualiza uma release no Archyl a partir do seu pipeline de CI. Registre deploys, associe-os a ambientes e elementos C4 e alimente suas 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

Saídas

Sync

Sincroniza seu arquivo DSL archyl.yaml com o Archyl. Declare sua arquitetura como código e envie as alterações a cada commit.

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

Entradas

Saídas

Workflows Reutilizáveis

O Archyl oferece dois workflows reutilizáveis que combinam várias actions para os cenários mais comuns.

archyl-pr.yml

Executa o conformance check e o drift score em paralelo em 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 as entradas são opcionais, exceto organization-id, project-id e api-key.

archyl-main.yml

Executa generate-context, sync e release a cada push na main. Cada job pode ser ativado ou desativado de forma independente.

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

Outras Plataformas de CI

GitLab CI

O Archyl oferece um template de CI para incluir no GitLab. Ele executa o conformance check e o drift score em merge requests e gera o contexto a cada push na branch padrão.

Configuração:

1. Adicione as variáveis de CI/CD necessárias em Configurações > CI/CD > Variáveis:

   • ARCHYL_API_KEY (mascarada, protegida)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Inclua o template no seu .gitlab-ci.yml:

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

Isso adiciona três jobs ao seu pipeline:

• archyl:conformance -- executado em merge requests
• archyl:drift-score -- executado em merge requests
• archyl:generate-context -- executado a cada push na branch padrão

Variáveis opcionais: ARCHYL_API_URL, ARCHYL_DRIFT_THRESHOLD.

Bitbucket Pipelines

Copie o template de pipelines do Archyl para o seu bitbucket-pipelines.yml.

Configuração:

1. Adicione as variáveis de repositório necessárias em Configurações > Variáveis do repositório:

   • ARCHYL_API_KEY (protegida)
   • ARCHYL_ORG_ID
   • ARCHYL_PROJECT_ID

2. Adicione as etapas do 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

O template completo está disponível em archyl-com/actions/ci-templates/bitbucket/archyl-pipelines.yml.

Exemplo Combinado

Um workflow completo que usa as 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 }}

Visualizando os Resultados

Os resultados de todas as verificações disparadas pelo CI aparecem no Archyl:

• Verificações de conformidade -- visíveis no painel de conformidade (aba Hub de Agentes > Painel). Clique em qualquer verificação para ver as violações agrupadas por arquivo.
• Pontuações de desvio -- visíveis na seção de desvio arquitetural do seu projeto. Acompanhe o histórico da pontuação ao longo do tempo.
• Solicitações de mudança -- visíveis na seção Solicitações. Revise as mudanças de arquitetura antes de aceitá-las.
• Releases -- visíveis na seção Releases e na página Ambientes. Alimentam suas métricas DORA.
• Resultados da sincronização -- refletidos imediatamente no seu modelo C4.

Consulte Regras de Conformidade para mais detalhes sobre o painel de conformidade.

Archyl Auto-hospedado

Se você executa o Archyl on-premise, defina a entrada api-url de qualquer action para apontar para a sua instância:

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

O padrão é https://api.archyl.com para todas as actions.