CI/CD no Protheus em 2026: pipeline real com TOTVS Cloud

Em 2026, ainda existe consultoria que faz deploy de RPO custom copiando arquivo na mao pro servidor. Enquanto isso, time da TOTVS publicou em 2025 um repositorio oficial mostrando exatamente como montar uma pipeline de CI/CD na T-Cloud. A maioria nem sabe que existe.

Este guia destrincha o pipeline em 5 etapas, mostra YAML real do GitHub Actions que voce cola e adapta, e aponta os 4 erros mais comuns que matam o pipeline na primeira tentativa.

Por que CI/CD virou mandatorio no Protheus

Tres mudancas estruturais nos ultimos 18 meses tornam CI/CD nao-opcional:

1. Reforma Tributaria 2026: CFGTRIB exige iteracoes rapidas de regras fiscais. Sem pipeline, cada ajuste vira janela de manutencao.
2. TLPP: linter e analise estatica so fazem sentido se rodam automatico em cada commit.
3. T-Cloud: a TOTVS facilitou patches via API, mas a maioria das consultorias ainda nao automatizou.

As 5 etapas do pipeline TOTVS oficial

Cada etapa falha rapido e bloqueia o merge. Ninguem promove rascunho.

Etapa 1 — Code Analysis: TLPP-lint

Antes de gastar tempo compilando, valide a qualidade. Use o tlpp-lint da TOTVS (instalado via VSCode marketplace):

# .github/workflows/protheus-ci.yml
name: Protheus CI/CD
on:
  push:
    branches: [main, develop]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with: { node-version: '20' }
      - name: Install tlpp-lint
        run: npm install -g @totvs/tlpp-lint
      - name: Run lint
        run: tlpp-lint ./src --strict --reporter=github

Configura no .tlpp-lint.json as regras que importam pra equipe:

{
  "rules": {
    "no-magic-numbers": "warn",
    "max-function-length": ["error", 50],
    "require-explicit-types": "error",
    "prefer-tlpp-namespace": "warn",
    "no-deprecated-functions": "error",
    "indent": ["error", 4]
  }
}

Etapa 2 — Build: gerando RPO custom

O build acontece em container TOTVS oficial (publicado em tcloud.totvs.com.br/protheus-build). YAML simplificado:

  build:
    needs: lint
    runs-on: ubuntu-latest
    container:
      image: totvs/protheus-build:12.1.2410
      credentials:
        username: ${{ secrets.TCLOUD_USER }}
        password: ${{ secrets.TCLOUD_PASS }}
    steps:
      - uses: actions/checkout@v4
      - name: Compile to RPO
        run: |
          tlpp build \
            --source ./src \
            --output ./build/customer.rpo \
            --include /opt/totvs/include
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: rpo-${{ github.sha }}
          path: build/customer.rpo
          retention-days: 14

Etapa 3 — TIR: testes automatizados

O TIR (TOTVS Integration Recipes) executa cenarios reais contra o RPO recem-buildado. Estrutura tipica:

Exemplo de caso TIR (.tir.json):

{
  "name": "Calculo IBS - operacao interestadual SP-RJ",
  "module": "FAT",
  "setup": [
    "INSERT INTO SF1010 (F1_DOC, F1_FORNECE) VALUES ('001', '000001')",
    "EXEC FISA170_SETUP_TEST_RULES"
  ],
  "actions": [
    { "function": "FAT_CALC_IBS", "args": ["001", "SP", "RJ"] }
  ],
  "expect": {
    "ibsTotal": 175.20,
    "tolerance": 0.01
  },
  "teardown": ["DELETE FROM SF1010 WHERE F1_DOC = '001'"]
}

Etapa 4 — Patch Generation

O patch e o pacote que sera enviado pra T-Cloud. Inclui RPO + scripts de banco + dicionario de dados:

  patch:
    needs: tir
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with: { name: rpo-${{ github.sha }} }
      - name: Generate patch
        run: |
          tlpp patch generate \
            --rpo ./customer.rpo \
            --sx-changes ./db/sx-changes.json \
            --output ./patches/patch-${{ github.sha }}.zip

Etapa 5 — Deploy na T-Cloud

A TOTVS oferece um Aplicador de Patches oficial pra T-Cloud (consulte o procedimento atual na Central de Atendimento TOTVS). Em pipelines maduros, o caminho recomendado e abrir um ticket automatizado ou usar o portal — endpoints diretos da T-Cloud nao sao publicos e variam por contrato/cliente.

  # CONCEITUAL — adapte para o canal de deploy oficial da sua conta T-Cloud
  deploy-dev:
    needs: patch
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
      - name: Apply patch on DEV
        env:
          TCLOUD_TOKEN: ${{ secrets.TCLOUD_API_TOKEN }}
        run: |
          # Substitua pelo procedimento oficial fornecido pela TOTVS
          # (Aplicador de Patches, portal, API privada por contrato, etc.)
          ./scripts/apply-patch-tcloud.sh \
            --patch patches/patch-${{ github.sha }}.zip \
            --env dev
      - name: Smoke test
        run: |
          sleep 30
          curl -fsS https://dev.cliente.com.br/api/health
      - name: Notify Slack
        uses: slackapi/slack-github-action@v1
        with:
          payload: '{"text":"Deploy DEV ${{ github.sha }} aplicado"}'

Erros que matam o pipeline na primeira tentativa

Proximos passos: blue-green com Protheus

Com o pipeline rodando, o proximo nivel e blue-green deployment: voce mantem 2 ambientes T-Cloud espelhados, faz deploy no inativo (green), valida com trafego sintetico, e troca o load balancer. Downtime ≈ 0.

A TOTVS ainda nao publicou playbook oficial pra blue-green em Protheus, mas a arquitetura ja e suportada. Fale conosco se quer um POC.

Fontes oficiais

• Repositorio oficial TOTVS de CI/CD pra Protheus (referencia primaria deste artigo): github.com/totvs/protheus-ci-universo
• Esteira CI/CD do TOTVS HTML Framework (TDN — exemplo de pipeline TOTVS interno em Azure DevOps): tdn.totvs.com/pages/viewpage.action?pageId=809138564
• Container oficial de build Protheus: tcloud.totvs.com.br/protheus-build
• Central de Atendimento TOTVS (procedimentos T-Cloud, suporte): centraldeatendimento.totvs.com