# GitHub Actions CI/CD Guide - SIGED Sistema Militar

Guia completo para configuração de integração contínua e deployment automático usando GitHub Actions.

## Índice

1. [Pré-requisitos](#pré-requisitos)
2. [Configuração de Secrets](#configuração-de-secrets)
3. [Workflows Disponíveis](#workflows-disponíveis)
4. [Monitoramento de Builds](#monitoramento-de-builds)
5. [Troubleshooting](#troubleshooting)

## Pré-requisitos

- Repositório GitHub
- Acesso ao repositório (permissões de admin)
- Servidor de produção com acesso SSH
- Conta de terceiros (Slack, Codecov - opcional)

## Configuração de Secrets

GitHub Secrets são variáveis criptografadas usadas nos workflows.

### Acessar Secrets

1. Ir para: **Settings > Secrets and variables > Actions**
2. Clicar em **"New repository secret"**

### Secrets Necessários para CI

```
CODECOV_TOKEN
  Descrição: Token do Codecov para upload de coverage
  Link: https://codecov.io/github/seu-usuario/seu-repo
```

### Secrets Necessários para Deploy

```
DEPLOY_HOST
  Descrição: Endereço IP ou domínio do servidor
  Exemplo: 192.168.1.100 ou app.example.com

DEPLOY_USER
  Descrição: Usuário SSH do servidor
  Exemplo: deploy ou ubuntu

DEPLOY_KEY
  Descrição: Chave SSH privada para acesso ao servidor
  Como gerar:
  ssh-keygen -t rsa -b 4096 -f deploy_key
  # Copiar conteúdo de deploy_key (chave privada)

DEPLOY_PORT
  Descrição: Porta SSH do servidor
  Padrão: 22

DEPLOY_PATH
  Descrição: Caminho do projeto no servidor
  Exemplo: /var/www/html/siged

SLACK_WEBHOOK
  Descrição: URL de webhook do Slack para notificações
  Como obter: https://api.slack.com/messaging/webhooks
  Formato: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
```

### Como Adicionar Secrets

#### Via Interface Web

1. Clicar em **"New repository secret"**
2. Nome: `DEPLOY_HOST`
3. Value: `seu-servidor.com`
4. Clicar em **"Add secret"**

#### Via GitHub CLI

```bash
# Instalar GitHub CLI: https://cli.github.com/

# Adicionar secrets
gh secret set DEPLOY_HOST -b "seu-servidor.com"
gh secret set DEPLOY_USER -b "deploy"
gh secret set DEPLOY_PORT -b "22"
gh secret set DEPLOY_PATH -b "/var/www/html/siged"

# Listar secrets
gh secret list

# Remover secret
gh secret delete DEPLOY_HOST
```

## Configuração SSH para Deploy

### 1. Gerar Chave SSH no Servidor

```bash
# No seu computador local
ssh-keygen -t rsa -b 4096 -f deploy_key -N ""

# Sem passphrase, apenas Enter quando solicitado
```

### 2. Adicionar Chave Pública ao Servidor

```bash
# Copiar chave pública para servidor
ssh-copy-id -i deploy_key.pub deploy@seu-servidor.com

# Ou manualmente
cat deploy_key.pub | ssh deploy@seu-servidor.com "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
```

### 3. Adicionar Chave Privada ao GitHub

```bash
# Copiar conteúdo da chave privada
cat deploy_key

# Colar em: Settings > Secrets > New secret
# Nome: DEPLOY_KEY
# Colar conteúdo de deploy_key
```

### 4. Teste de Conexão

```bash
ssh -i deploy_key deploy@seu-servidor.com "echo 'SSH funciona!'"
```

## Workflows Disponíveis

### 1. Run Tests CI (`.github/workflows/run-tests.yml`)

**Trigger:** Push ou Pull Request em `main` ou `develop`

**Passos:**
1. Checkout do código
2. Setup PHP 8.2
3. Cache de dependências Composer
4. Instalar dependências
5. Gerar chave da aplicação
6. Aguardar MySQL
7. Rodar migrations
8. Executar testes com coverage
9. Upload para Codecov

**Como ver resultados:**
- Ir para **Actions** tab no repositório
- Clicar no workflow run
- Ver detalhes de sucesso/falha

**Exemplos de uso:**

```bash
# Fazer commit (dispara CI)
git add .
git commit -m "Nova feature"
git push origin develop

# CI rodará automaticamente
# Aguardar resultado em GitHub Actions
```

### 2. Deploy to Production (`.github/workflows/deploy.yml`)

**Trigger:** Push para `main` branch

**Pré-requisitos:**
- Todos os testes devem passar
- Secrets configurados

**Passos:**
1. Checkout do código
2. Pre-deployment checks
3. Conectar via SSH
4. Pull código
5. Instalar dependências Composer
6. Instalar dependências JavaScript
7. Rodar migrations
8. Clear caches
9. Notificar via Slack

**Configuração do Deploy:**

```yaml
# Adicionar ao deploy.yml
- name: Deploy via SSH
  env:
    # Variáveis de ambiente do deploy
    APP_ENV: production
    APP_DEBUG: false
```

**Como disparar deploy:**

```bash
# Merge para main dispara deploy
git checkout main
git merge develop
git push origin main

# Deploy começa automaticamente
# Monitore em: Actions > Deploy to Production
```

## Monitoramento de Builds

### 1. Ver Status dos Workflows

**Via Interface Web:**
1. Ir para **Actions** tab
2. Ver todos os runs
3. Clicar em um run para detalhes

**Via GitHub CLI:**

```bash
# Listar runs recentes
gh run list --limit 10

# Ver detalhes de um run específico
gh run view <run-id>

# Ver logs
gh run view <run-id> --log
```

### 2. Status Badge

Adicionar badge de status no README:

```markdown
![CI/CD Tests](https://github.com/seu-usuario/SIGED/workflows/Run%20Tests/badge.svg)
![Deployment](https://github.com/seu-usuario/SIGED/workflows/Deploy%20to%20Production/badge.svg)
```

### 3. Notificações via Slack

As notificações são enviadas automaticamente quando:
- ✅ Deploy bem-sucedido
- ❌ Deploy falhou
- 🔔 Testes falharam

**Customizar Slack Webhook:**

```bash
# Ver webhooks configurados
gh secret list

# Atualizar webhook
gh secret set SLACK_WEBHOOK -b "https://hooks.slack.com/..."
```

### 4. Email Notifications

GitHub envia emails por padrão. Para customizar:

1. Ir para **Settings > Notifications**
2. Configurar preferências de email

## Troubleshooting

### Workflow Falhando: Testes

```bash
# Verificar logs no GitHub Actions
# Ir para: Actions > run > test > logs

# Possíveis causas:
# 1. Dependências não instaladas
#    - Verificar composer.lock
#    - Rodar localmente: composer install

# 2. Banco de dados não pronto
#    - Verificar health check do MySQL
#    - Aumentar timeout

# 3. Variáveis de ambiente
#    - Verificar .env.example
#    - Adicionar ao workflow
```

### Workflow Falhando: Deploy

```bash
# Causas comuns:

# 1. SSH Key inválida
#    - Verificar se deploy_key é privada (começa com -----BEGIN RSA PRIVATE KEY-----)
#    - Ter certeza que .pub está no servidor

# 2. Host desconhecido
#    - Adicionar ao known_hosts:
#      ssh-keyscan seu-servidor.com >> ~/.ssh/known_hosts
#    - Ou adicionar no workflow:
#      mkdir -p ~/.ssh
#      ssh-keyscan seu-servidor.com >> ~/.ssh/known_hosts

# 3. Permissões de arquivo
#    - Verificar permissões da chave privada
#    - chmod 600 deploy_key

# 4. Path do deployment
#    - Verificar DEPLOY_PATH existe no servidor
#    - mkdir -p /var/www/html/siged
```

### Logs Não Aparecem

```bash
# Usar GitHub CLI para ver logs completos
gh run view <run-id> --log > run-logs.txt

# Ou dentro do workflow, adicionar:
- name: Debug
  run: |
    echo "Current directory: $(pwd)"
    ls -la
    php artisan config:show
```

## Configurações Avançadas

### 1. Executar Apenas em Determinadas Branches

```yaml
on:
  push:
    branches:
      - main
      - develop
      - 'release/**'
```

### 2. Matrix Testing (Múltiplas Versões)

```yaml
strategy:
  matrix:
    php-version: ['8.1', '8.2', '8.3']
    os: [ubuntu-latest, windows-latest]
```

### 3. Conditional Steps

```yaml
- name: Deploy
  if: github.ref == 'refs/heads/main' && success()
  run: ./scripts/deploy.sh
```

### 4. Artifacts e Caching

```yaml
- name: Upload Test Results
  uses: actions/upload-artifact@v3
  with:
    name: test-results
    path: storage/logs/
```

## Schedule: CI/CD Agendado

### Testes Diários

```yaml
on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM todos os dias
```

### Database Cleanup Semanal

```yaml
on:
  schedule:
    - cron: '0 3 * * 0'  # 3 AM todo domingo
```

## Integração com Outras Ferramentas

### SonarQube para Code Quality

```yaml
- name: SonarQube Scan
  uses: SonarSource/sonarcloud-github-action@master
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
```

### SendGrid para Notificações de Email

```yaml
- name: Send Email Notification
  uses: dawidd6/action-send-mail@v3
  with:
    server_address: smtp.sendgrid.net
    server_port: 465
    username: apikey
    password: ${{ secrets.SENDGRID_API_KEY }}
    subject: Deploy Status
    to: admin@siged.com
```

## Boas Práticas

1. **Sempre rodar testes:** Não fazer deploy sem que testes passem
2. **Versionamento:** Usar tags para releases
3. **Secrets seguros:** Nunca commitar secrets
4. **Documentação:** Manter workflows documentados
5. **Monitoramento:** Verificar status regularmente
6. **Alertas:** Configurar notificações para erros

## Recursos Adicionais

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [GitHub Actions Marketplace](https://github.com/marketplace?type=actions)
- [Codecov](https://codecov.io/)
- [Slack Webhooks](https://api.slack.com/messaging/webhooks)

## Suporte

Para dúvidas ou problemas:
- Consultar [GitHub Actions Docs](https://docs.github.com/en/actions)
- Abrir issue no repositório
- Contatar time de DevOps