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 AIOX.

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:

Regra de Proteção	Recomendação	Justificativa
Reviews de pull request obrigatórios	Habilitar com 1-2 revisores	Previne código não revisado de ser mergeado
Exigir reviews de code owner	Habilitar	Garante que especialistas de domínio revisem mudanças relevantes
Descartar reviews obsoletas	Habilitar	Força re-review após novas mudanças
Status checks obrigatórios	CI deve passar	Captura falhas de build/teste antes do merge
Exigir resolução de conversas	Habilitar	Garante que todo feedback seja endereçado
Restringir force pushes	Desabilitar force push	Previne reescrita de histórico
Exigir histórico linear	Opcional	Histórico git mais limpo (considerar para monorepos)

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:

Elemento	Propósito	Recomendação
`language`	Idioma de resposta	Corresponder ao idioma do projeto (pt-BR ou en-US)
`reviews.auto_review`	Reviews automáticos de PR	Habilitar para OSS
`reviews.path_instructions`	Regras de review customizadas por caminho	Essencial para validação de agent/task
`chat.auto_reply`	Responder a comentários	Habilitar para melhor experiência do contribuidor

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 AIOX

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

Estrutura YAML do agente - persona_profile, commands, dependencies
Formato de task - elicitation points, deliverables
Documentação - Atualizações de README, referências de guias
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:

Princípio	Descrição
Último match vence	Padrões posteriores sobrescrevem anteriores
Usar wildcards	Consolidar entradas com `` e `*`
Teams sobre usuários	Mais fácil de manter quando pessoas mudam
Granularidade	Balancear entre muito amplo e muito específico

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 AIOX

# Padrão - requer review de maintainer
* @SynkraAI/maintainers

# Definições de agentes - requer core team
.aiox-core/development/agents/ @SynkraAI/core-team

# Definições de tasks - requer core team
.aiox-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
.aiox-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

Verificação	Tipo	Prioridade
`lint`	Obrigatório	ALTA
`typecheck`	Obrigatório	ALTA
`build`	Obrigatório	ALTA
`test`	Obrigatório	ALTA
`story-validation`	Opcional	MÉDIA
`ide-sync-validation`	Opcional	BAIXA
`alls-green`	Obrigatório	ALTA (job resumo)

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:

Clonar repositório
Criar branch de feature
Fazer mudanças + testes
Submeter PR com descrição
Assinar CLA
Aguardar review

5.3 Padrões Comuns

Padrão	Adoção	Recomendação
Workflow de fork	Muito comum	Adotar
Assinatura de CLA	Comum em OSS corporativo	Opcional por agora
Conventional commits	Muito comum	Já adotado
Aprovações obrigatórias	Universal	Adotar (1 aprovação)
CODEOWNERS	Comum	Adotar (granular)
CodeRabbit/AI review	Crescendo	Adotar

6. Considerações de Segurança

6.1 Workflow de Fork vs Branch Direta

Aspecto	Workflow de Fork	Branch Direta
Segurança	Maior (isolado)	Menor (repo compartilhado)
Acesso do contribuidor	Não precisa escrita	Acesso de escrita necessário
CI/CD	Roda no contexto do fork	Roda no repo principal
Secrets	Protegidos	Acessíveis
Complexidade	Ligeiramente maior	Menor

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 AIOX

7.1 Ações Imediatas (CRÍTICO)

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Pesquisa de Workflow de Contribuição Externa

Resumo Executivo

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

1.1 Recomendações da Indústria

1.2 Insights Principais

1.3 Configurações Recomendadas para Open Source

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

2.1 Documentação Oficial

2.2 Exemplos do Mundo Real

2.3 Recomendações Específicas para AIOX

3. Melhores Práticas de CODEOWNERS

3.1 Padrões da Indústria

3.2 Padrões de Monorepo

3.3 Estrutura Específica do AIOX

4. GitHub Actions Required Checks

4.1 Melhores Práticas

4.2 Verificações Obrigatórias Recomendadas

5. Exemplos de Workflow de Contribuição OSS

5.1 Next.js

5.2 Prisma

5.3 Padrões Comuns

6. Considerações de Segurança

6.1 Workflow de Fork vs Branch Direta

6.2 Protegendo Secrets em PRs

7. Recomendações para AIOX

7.1 Ações Imediatas (CRÍTICO)

7.2 Ações de Curto Prazo (ALTO)

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

7.4 Baixa Prioridade (BOM TER)

8. Fontes

Proteção de Branch

CodeRabbit

CODEOWNERS

GitHub Actions

Exemplos OSS

FilesExpand file tree

contribution-workflow-research.md

Latest commit

History

contribution-workflow-research.md

File metadata and controls

Pesquisa de Workflow de Contribuição Externa

Resumo Executivo

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

1.1 Recomendações da Indústria

1.2 Insights Principais

1.3 Configurações Recomendadas para Open Source

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

2.1 Documentação Oficial

2.2 Exemplos do Mundo Real

2.3 Recomendações Específicas para AIOX

3. Melhores Práticas de CODEOWNERS

3.1 Padrões da Indústria

3.2 Padrões de Monorepo

3.3 Estrutura Específica do AIOX

4. GitHub Actions Required Checks

4.1 Melhores Práticas

4.2 Verificações Obrigatórias Recomendadas

5. Exemplos de Workflow de Contribuição OSS

5.1 Next.js

5.2 Prisma

5.3 Padrões Comuns

6. Considerações de Segurança

6.1 Workflow de Fork vs Branch Direta

6.2 Protegendo Secrets em PRs

7. Recomendações para AIOX

7.1 Ações Imediatas (CRÍTICO)

7.2 Ações de Curto Prazo (ALTO)

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

7.4 Baixa Prioridade (BOM TER)

8. Fontes

Proteção de Branch

CodeRabbit

CODEOWNERS

GitHub Actions

Exemplos OSS