Pesquisa de Workflow de Contribuição Externa

🌐 EN | PT | ES

Story: COLLAB-1 Data: 2025-12-30 Autor: @dev (Dex) + @devops (Gage) Status: Completo

Resumo Executivo

Este documento consolida as descobertas de pesquisa sobre melhores práticas para workflows de contribuidores externos em projetos open source, especificamente para habilitar contribuições seguras da comunidade para agentes e tarefas do AIOS.

1. Melhores Práticas de Proteção de Branch no GitHub

1.1 Recomendações da Indústria

Baseado em pesquisa da GitHub Docs , DEV Community , e Legit Security :

1.2 Insights Principais

“Colaboradores com acesso de escrita a um repositório têm permissões completas de escrita em todos os seus arquivos e histórico. Embora isso seja bom para colaboração, nem sempre é desejável.”

Ponto Crítico: Proteção de branch é uma das considerações de segurança mais importantes. Pode prevenir que código indesejado seja enviado para produção.

1.3 Configurações Recomendadas para Open Source

branch_protection:
  require_pull_request_reviews:
    required_approving_review_count: 1 # Pelo menos 1 aprovação
    dismiss_stale_reviews: true # Re-review após mudanças
    require_code_owner_reviews: true # Aprovação de especialista de domínio
    require_last_push_approval: false # Opcional para OSS
 
  required_status_checks:
    strict: true # Branch deve estar atualizado
    contexts:
      - lint
      - typecheck
      - build
      - test # Crítico para qualidade
 
  restrictions:
    users: []
    teams: ['maintainers']
 
  allow_force_pushes: false
  allow_deletions: false
  required_conversation_resolution: true # Endereçar todo feedback

2. Melhores Práticas de Configuração do CodeRabbit

2.1 Documentação Oficial

Da CodeRabbit Docs  e awesome-coderabbit :

Elementos Principais de Configuração:

2.2 Exemplos do Mundo Real

TEN Framework (.coderabbit.yaml):

language: 'en-US'
reviews:
  profile: 'chill'
  high_level_summary: true
  auto_review:
    enabled: true
tools:
  ruff:
    enabled: true
  gitleaks:
    enabled: true

Projeto PHARE:

path_instructions:
  '**/*.cpp':
    - 'Verificar memory leaks'
    - 'Verificar thread safety'
tools:
  shellcheck:
    enabled: true
  markdownlint:
    enabled: true

NVIDIA NeMo RL:

auto_title_instructions: |
  Formato: "<categoria>: <título>"
  Categorias: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
  Título deve ter <= 80 caracteres

2.3 Recomendações Específicas para AIOS

Para contribuições de agent/task, o CodeRabbit deve validar:

1. Estrutura YAML do agente - persona_profile, commands, dependencies
2. Formato de task - elicitation points, deliverables
3. Documentação - Atualizações de README, referências de guias
4. Segurança - Sem secrets hardcoded, permissões apropriadas

3. Melhores Práticas de CODEOWNERS

3.1 Padrões da Indústria

Da Harness Blog , Satellytes , e GitHub Docs :

Princípios Principais:

3.2 Padrões de Monorepo

# Owner padrão (fallback)
* @org/maintainers
 
# Ownership de diretório (mais específico)
/src/auth/ @org/security-team
/src/api/ @org/backend-team
/src/ui/ @org/frontend-team
 
# Ownership por tipo de arquivo
*.sql @org/dba-team
Dockerfile @org/devops-team
 
# Arquivos críticos (requerem review sênior)
/.github/ @org/core-team
/security/ @org/security-team

3.3 Estrutura Específica do AIOS

# Padrão - requer review de maintainer
* @SynkraAI/maintainers
 
# Definições de agentes - requer core team
.aios-core/development/agents/ @SynkraAI/core-team
 
# Definições de tasks - requer core team
.aios-core/development/tasks/ @SynkraAI/core-team
 
# CI/CD - requer aprovação devops
.github/ @SynkraAI/devops
 
# Documentação - mais permissivo para contribuidores
docs/ @SynkraAI/maintainers
 
# Templates - requer review de architect
templates/ @SynkraAI/core-team
.aios-core/product/templates/ @SynkraAI/core-team

4. GitHub Actions Required Checks

4.1 Melhores Práticas

Da GitHub Docs  e discussões da comunidade:

Insight Crítico:

“Se uma verificação falha, o GitHub previne o merge do PR. No entanto, jobs pulados reportam ‘Success’ e não previnem merge.”

Padrão de Solução (job alls-green):

jobs:
  lint:
    runs-on: ubuntu-latest
    # ...
 
  test:
    runs-on: ubuntu-latest
    # ...
 
  alls-green:
    name: Todas Verificações Passaram
    runs-on: ubuntu-latest
    needs: [lint, test]
    if: always()
    steps:
      - name: Verificar se todos os jobs passaram
        run: |
          if [ "${{ needs.lint.result }}" != "success" ]; then exit 1; fi
          if [ "${{ needs.test.result }}" != "success" ]; then exit 1; fi

4.2 Verificações Obrigatórias Recomendadas

5. Exemplos de Workflow de Contribuição OSS

5.1 Next.js

Do Next.js Contribution Guide :

• Workflow de fork e PR
• Verificação automatizada de formatação Prettier
• Requer review de PR de maintainers
• Usa Turborepo para gerenciamento de monorepo

5.2 Prisma

Do Prisma CONTRIBUTING.md :

Requisitos Principais:

• Assinatura de CLA obrigatória
• Mensagens de commit estruturadas
• Testes devem cobrir mudanças
• Tamanho do bundle monitorado (<6MB)
• CI/CD deve passar (lint, test, cross-platform)

Workflow:

1. Clonar repositório
2. Criar branch de feature
3. Fazer mudanças + testes
4. Submeter PR com descrição
5. Assinar CLA
6. Aguardar review

5.3 Padrões Comuns

6. Considerações de Segurança

6.1 Workflow de Fork vs Branch Direta

Recomendação: Workflow de fork para contribuidores externos (já documentado em CONTRIBUTING.md)

6.2 Protegendo Secrets em PRs

• Nunca expor secrets em logs de CI
• Usar pull_request_target com cuidado
• Limitar escopos de secrets
• Auditar autores de PR para padrões suspeitos

7. Recomendações para AIOS

7.1 Ações Imediatas (CRÍTICO)

1. Habilitar reviews de aprovação obrigatórios (required_approving_review_count: 1)
2. Habilitar reviews de code owner (require_code_owner_reviews: true)
3. Adicionar test aos status checks obrigatórios

7.2 Ações de Curto Prazo (ALTO)

1. Criar .coderabbit.yaml com instruções de path específicas do AIOS
2. Atualizar CODEOWNERS com ownership granular
3. Habilitar resolução de conversas obrigatória

7.3 Ações de Médio Prazo (MÉDIO)

1. Criar templates de PR especializados para contribuições de agent/task
2. Aprimorar CONTRIBUTING.md com checklist de contribuição de agente
3. Adicionar guia de onboarding de contribuidor

7.4 Baixa Prioridade (BOM TER)

1. Adicionar bot de CLA para proteção legal
2. Implementar automação de PR obsoleto
3. Adicionar dashboard de métricas de contribuição

8. Fontes

Proteção de Branch

• GitHub Docs: Managing Branch Protection Rules 
• DEV Community: Best Practices for Branch Protection 
• Legit Security: GitHub Security Best Practices 

CodeRabbit

• CodeRabbit YAML Configuration 
• awesome-coderabbit Repository 
• TEN Framework .coderabbit.yaml 

CODEOWNERS

• Harness: Mastering CODEOWNERS 
• GitHub Docs: About Code Owners 
• Satellytes: Monorepo CODEOWNERS 

GitHub Actions

• GitHub Docs: About Status Checks 
• GitHub Blog: Required Workflows 

Exemplos OSS

• Next.js Contribution Guide 
• Prisma CONTRIBUTING.md 

Documento gerado como parte da investigação da Story COLLAB-1.