Azure DevOps - Configuração de Branch Policies

🎯 Objetivo

Configurar proteções na branch main para garantir qualidade e rastreabilidade do código em produção.

📋 Pré-requisitos

Branch dev criada e publicada
Pipeline CI configurado (Backend CI - API & Worker)
Permissões de administrador no repositório Azure DevOps

🔧 Passo a Passo

1. Acessar Branch Policies

Abrir Azure DevOps: https://dev.azure.com/[sua-organizacao]/Audissey
Navegar: Repos → Branches
Localizar branch main
Click nos 3 pontos (⋯) ao lado de main
Selecionar Branch policies

2. Configurar Minimum Reviewers

Seção: "Require a minimum number of reviewers"

✅ Enable this policy

Configurações:
├─ Minimum number of reviewers: 1
├─ ❌ Allow requestors to approve their own changes
├─ ✅ Prohibit the most recent pusher from approving
├─ ✅ Allow completion even if some reviewers vote to wait or reject
│    (Recomendado: ❌ deixar desabilitado para forçar consenso)
└─ When new changes are pushed:
   └─ ✅ Reset all approval votes (recommended)

Resultado: Commits diretos bloqueados, pelo menos 1 aprovação necessária.

3. Configurar Build Validation

Seção: "Build validation"

Click ➕ Add build policy
Configurar:

Build pipeline: Backend CI - API & Worker
Path filter: (deixar vazio para todos os arquivos)
Trigger: Automatic
Policy requirement: Required
Build expiration: Immediately when main is updated
Display name: CI Validation (Main)

Click Save

Resultado: PRs só podem ser merged se pipeline passar.

4. Configurar Comment Resolution

Seção: "Check for comment resolution"

✅ Required

Configurações:
└─ All comments must be resolved before completion

Resultado: Todas as observações devem ser resolvidas antes do merge.

5. Configurar Linked Work Items

Seção: "Check for linked work items"

⚠️ Optional (ou Required conforme preferência)

Configurações:
└─ Encourage or require association with a work item

Resultado: Rastreabilidade entre código e user stories/tasks.

6. Limitar Tipos de Merge

Seção: "Limit merge types"

✅ Basic merge (não squash): ❌ Desabilitar
✅ Squash merge: ✅ Habilitar
✅ Rebase and fast-forward: ❌ Desabilitar
✅ Rebase with merge commit: ❌ Desabilitar

Default merge type: Squash commit

Resultado: Histórico limpo com 1 commit por feature.

7. Configurar Status Checks (Opcional)

Seção: "Status check"

Adicionar validações extras se houver integrações:

SonarQube analysis
Security scans
License compliance

Click ➕ "Add status policy" se aplicável

🔒 Configuração Final da Branch Main

Após seguir todos os passos, as políticas devem estar:

Branch: main

✅ Require a minimum number of reviewers (1)
   ├─ Reset votes on push
   └─ Prohibit last pusher approval

✅ Build validation
   └─ Backend CI - API & Worker (Required)

✅ Check for comment resolution (Required)

⚠️ Check for linked work items (Optional)

✅ Limit merge types
   └─ Squash merge only

🔄 Configurar Branch Dev (Opcional mas Recomendado)

Repetir processo para dev com regras relaxadas:

Navegar para branch dev → Branch policies
Configurar:

✅ Build validation (Required)
   └─ Backend CI - API & Worker

⚠️ Minimum reviewers (Optional)
   └─ Reviewers: 0 (apenas sugestão)

✅ Limit merge types
   └─ Allow all types

Benefício: CI valida antes do merge, mas processo mais ágil.

🏷️ Definir Default Branch

Navegar: Project Settings (canto inferior esquerdo)
Repositories → Selecionar Audissey
Settings tab
Default branch: Alterar para dev
Click Save

Resultado: Pull requests e clones usarão dev por padrão.

✅ Validação

Testar Branch Protection

# 1. Tentar push direto para main (deve falhar)
git checkout main
echo "test" >> README.md
git add README.md
git commit -m "test: direct push"
git push origin main

# Esperado: ❌ Error - TF402455: Pushes to this branch are not permitted

# 2. Criar PR corretamente
git checkout dev
git checkout -b feature/test-protection
echo "# Test" >> test.md
git add test.md
git commit -m "feat: test branch protection"
git push -u origin feature/test-protection

# 3. Criar PR via Azure DevOps UI
# 4. Verificar que CI roda automaticamente
# 5. Verificar que "Complete" está bloqueado até aprovação

Checklist de Verificação

Push direto para main bloqueado
PR requer aprovação de reviewer
Build validation roda automaticamente
Comentários devem ser resolvidos
Squash merge é padrão
Default branch é dev

📊 Exemplo de PR Workflow

Criar Feature

git checkout dev
git pull origin dev
git checkout -b feature/user-favorites
# ... desenvolver ...
git push -u origin feature/user-favorites

Abrir PR (via Azure DevOps)

Repos → Pull Requests → New pull request
Preencher:
- Source: feature/user-favorites
- Target: dev
- Title: feat: implementar sistema de favoritos
- Description:
```
## Mudanças
- Adicionar endpoints de favoritos
- Criar schema Favorite
- Testes E2E completos

## Closes
#1234
```
- Reviewers: Adicionar membros da equipe
- Work Items: Link para user story
Pipeline CI roda automaticamente
Aguardar aprovação
Resolver comentários se houver
Complete (squash merge) → dev

Release para Produção

# Após features testadas em dev
git checkout dev
git pull origin dev
git checkout -b release/v1.2.0
git push -u origin release/v1.2.0

Criar PR de release/v1.2.0 → main:

## Release v1.2.0 - 27 Dezembro 2024

### 🎉 Features
- Sistema de favoritos para podcasts (#1234)
- Busca unificada com filtros (#1235)
- Player de rádio melhorado (#1236)

### 🐛 Bugfixes
- Corrigir race condition no sync (#1240)
- Resolver memory leak no worker (#1241)

### 📚 Documentation
- Atualizar API reference (#1242)

### 🔧 Chore
- Atualizar dependências (#1243)

🚨 Troubleshooting

Erro: "TF402455: Pushes to this branch are not permitted"

✅ Esperado: Branch protection funcionando
🔧 Solução: Criar feature branch e PR

Erro: "Build validation failed"

✅ Esperado: CI encontrou problemas
🔧 Solução:

# Rodar testes localmente
npm run lint
npm run test
npm run build

# Corrigir e fazer novo commit
git add .
git commit -m "fix: corrigir erros CI"
git push

Não consigo aprovar meu próprio PR

✅ Esperado: "Prohibit last pusher" ativado
🔧 Solução: Solicitar aprovação de outro membro

Pipeline não roda automaticamente

🔧 Verificar:

Build policy configurado como "Automatic"
Path filter correto (vazio = todos arquivos)
Pipeline permissions incluem branch

📚 Referências

📞 Suporte

Em caso de dúvidas sobre permissões ou configurações:

Verificar se usuário tem role de Project Administrator
Contactar administrador do Azure DevOps
Ver logs em Project Settings → Auditing

Próximos passos: Após configurar políticas, testar workflow criando PR de teste conforme seção "Validação".

Azure DevOps Branch Policies