Deploy — Visão Geral

Esta seção documenta o sistema de deploy do front-end da Cactus Gaming: como o front-web-base (e qualquer fork) é buildado e publicado no Cloudflare Workers, e como adicionar novos environments (setups), brands/forks e contas Cloudflare.

:::tip Quero adicionar um setup novo agora Vá direto para o passo a passo: Adicionar um novo environment. :::

Modelo: caller + reusable workflow

O deploy segue o padrão caller + reusable workflow, com o front-ops como única fonte de verdade:

┌──────────────────────────────┐         ┌──────────────────────────────────┐
│  front-web-base (caller)      │         │  front-ops (single source)        │
│  .github/workflows/           │         │  config/brands/web-base/          │
│    ci-deploy.yml              │         │    brand.yml                      │
│      • quality (lint/test)    │ ──────▶ │    cache.yml                      │
│      • resolve-matrix         │  chama  │    environments/<env>/deploy.yml  │
│      • deploy (matrix)        │         │  .github/workflows/deploy.yml     │
└──────────────────────────────┘         └──────────────────────────────────┘

• O caller (ci-deploy.yml no front-web-base) roda o quality gate (lint/check/typecheck/test), resolve a matriz de deploy lendo o front-ops, e chama o reusable workflow uma vez por environment.
• O reusable (deploy.yml no front-ops) é quem de fato resolve a config da brand/env, as credenciais Cloudflare, faz checkout do código do fork, builda e publica no Cloudflare Workers.

O fork não contém lógica de resolução de worker_name, tokens Cloudflare, política de cache ou pipeline de build/deploy. Tudo isso vive no front-ops.

O caller chama o reusable assim

# front-web-base/.github/workflows/ci-deploy.yml (trecho)
deploy:
  name: ${{ matrix.environment }}
  needs: [quality, resolve-matrix]
  if: needs.resolve-matrix.outputs.deploy_needed == 'true'
  strategy:
    fail-fast: false
    matrix:
      include: ${{ fromJson(needs.resolve-matrix.outputs.matrix) }}
  uses: cactus-agents/front-ops/.github/workflows/deploy.yml@main
  with:
    environment: ${{ matrix.environment }}
  secrets: inherit

:::caution Não existe input ref Diferente de versões antigas da doc, o reusable workflow não aceita um input ref. O branch que é deployado é sempre o default_branch declarado no front-ops (ver Branch governance abaixo). :::

Estrutura de config no front-ops

Convenção: uma brand = um repo. Cada environment é uma pasta com seu próprio deploy.yml.

front-ops/config/
├── cache/
│   └── defaults.yml                    # política de cache global (todas as brands)
└── brands/
    └── web-base/                       # brand (kebab-case)
        ├── brand.yml                   # identidade + defaults (declara `repo:`)
        ├── cache.yml                   # overrides de cache da brand (opcional)
        └── environments/
            ├── prod-7k-bet-br/
            │   └── deploy.yml          # config do env (fonte de verdade)
            ├── stage-7k-bet-br-cactusgaming-tech/
            │   └── deploy.yml
            └── <env>/
                ├── deploy.yml
                └── cache.yml           # overrides de cache do env (opcional)

O nome da pasta do environment é o id do environment (o que aparece no dropdown de workflow_dispatch e no scan de auto-deploy).

brand.yml

brand: web-base
repo: cactus-agents/front-web-base   # declara qual repo pertence à brand

defaults:
  default_branch: main
  language: pt-br
  auto_deploy: false

environments/<env>/deploy.yml

worker_name: front-web-7k-bet-br     # nome do Worker no Cloudflare (NUNCA vem de input)
cf_account: CT                       # prefixo da conta CF (2-4 letras maiúsculas)
auto_deploy: false                   # true = deploy automático no push do default_branch
default_branch: main                 # branch oficial deste env
language: pt-br
origin_domain: 7k.bet.br             # domínio servido / origin
worker_url: 7k.bet.br                # URL pública do worker (default: = origin_domain)
cf_zone: 7k.bet.br                   # zona CF apex p/ purge (ver Cache & Purge)

# Opcional — restringe quem pode dar deploy manual (workflow_dispatch)
deploy_protection:
  required_team: rulesets-groups-front-deployers-cactus-agents-front-web-base-reader

Campo	Obrigatório	Descrição
worker_name	✅	Nome do Worker no Cloudflare. Resolvido só do config (nunca de input externo).
cf_account	✅ (env ou default)	Prefixo da conta CF: CT, BT, TS.
origin_domain	✅	Domínio do origin / brand-key.
auto_deploy	— (default false)	true → deploy automático no push do default_branch.
default_branch	— (default main)	Branch oficial deployada deste env.
language	— (default pt-br)	BRAND_LANGUAGE.
worker_url	— (default = origin_domain)	URL pública usada em purge/warm-up/summary.
cf_zone	— (derivado)	Zona apex p/ purge SSR. Ver Cache & Purge.
deploy_protection.required_team	—	Org team que pode dar deploy manual.

Campos ausentes caem no fallback de brand.yml::defaults e, por fim, em defaults embutidos no workflow (default_branch: main, language: pt-br, auto_deploy: false).

Branch governance

O branch que é deployado para um env é sempre o default_branch declarado no front-ops. Não há override manual de ref em lugar nenhum.

Trigger	O que é deployado
push (auto-deploy)	O commit empurrado. A matriz só inclui envs cujo default_branch == github.ref_name e auto_deploy: true.
workflow_dispatch	HEAD SHA do default_branch no repo caller, resolvido via GitHub API em runtime.
pull_request	Nenhum deploy (só roda quality + config-lint).

:::info Sobre o "Use workflow from" da UI do GitHub A UI nativa de workflow_dispatch sempre mostra um dropdown "Use workflow from". Esse controle não tem efeito no código deployado — ele só escolhe qual versão do YAML do workflow roda. O código deployado é sempre o HEAD do default_branch do front-ops. :::

Rollback

Não há UI para deployar um SHA arbitrário. Para reverter, reverta no branch oficial:

git -C repos/front-web-base checkout <default_branch>
git -C repos/front-web-base revert <commit-ruim>
git -C repos/front-web-base push      # dispara auto-deploy, ou dispare manual

Multi-account Cloudflare

Cada environment pode apontar para uma conta CF diferente via cf_account. O valor é o prefixo (2-4 letras maiúsculas) das org secrets:

Nome	Prefixo	Secrets
Cactus	CT	FRONT_CT_CF_ACCOUNT_ID, FRONT_CT_CF_API_TOKEN
Bluetec	BT	FRONT_BT_CF_ACCOUNT_ID, FRONT_BT_CF_API_TOKEN
Teste	TS	FRONT_TS_CF_ACCOUNT_ID, FRONT_TS_CF_API_TOKEN

Ver Referência de secrets para a lista completa (incluindo purge, worker key e R2) e Adicionar conta CF.

O que o reusable workflow faz, passo a passo

1. Resolve config — acha a brand cujo repo: bate com o caller, lê environments/<env>/deploy.yml (com fallbacks de brand.yml).
2. Authorization gate (só em workflow_dispatch, se deploy_protection estiver setado) — verifica se o ator está no team exigido.
3. Resolve CF credentials — mapeia cf_account → org secrets FRONT_{PREFIX}_CF_ACCOUNT_ID / FRONT_{PREFIX}_CF_API_TOKEN.
4. Lê API_BASE_URL e CF_WORKER_KEY dos bindings do Worker já existente na CF (via API). ⚠️ Por isso o Worker precisa existir e ter essas vars antes do primeiro deploy automatizado — ver Adicionar environment.
5. Gera .env + builda (pnpm build) com BRAND_LANGUAGE, ORIGIN_DOMAIN, API_BASE_URL, CF_WORKER_KEY, GITHUB_SHA.
6. Resolve política de cache (defaults → brand → env) e provisiona KV se algum recurso usa snapshot KV.
7. Patch wrangler.toml — injeta [vars] (BUILD_ID, WORKER_NAME, PLATFORM_CACHE_POLICY_JSON, CACHE_NAMESPACE) e o binding [[kv_namespaces]].
8. Sync de assets para R2 (fallback de chunks antigos entre deploys).
9. wrangler deploy --name <worker_name> --keep-vars.
10. Purge pós-deploy — platform cache (por segmentos) + SSR cache (CF zone purge) + warm-up das rotas principais.

Workflows relacionados

Repo	Workflow	Função
front-web-base	ci-deploy.yml	CI (quality) + resolve matrix + chama reusable de deploy
front-web-base	list-environments.yml	Viewer read-only da topologia de envs (dispatch manual)
front-web-base	lighthouse.yml	Auditoria Lighthouse
front-web-base	delete-merged-branch.yml	Limpeza de branches mergeadas
front-ops	deploy.yml	Reusable de deploy (chamado pelos forks)
front-ops	deploy-docs.yml	Deploy do front-cactus-docs
front-ops	deploy-affiliates.yml	Deploy do cactus-affiliates
front-ops	lighthouse-base.yml	Lighthouse reusable
front-ops	manual-cache-purge.yml	Purge manual de cache

Regras de bloqueio de deploy

O reusable workflow falha o deploy quando:

• o repo caller não é declarado por nenhum brand.yml (campo repo:);
• o environment não existe (environments/<env>/deploy.yml ausente);
• mais de uma brand declara o mesmo repo: (conflito);
• worker_name não está definido no env;
• origin_domain não está definido;
• cf_account não está definido (nem no env, nem no default da brand);
• cf_account tem formato inválido (não são 2-4 letras maiúsculas);
• as org secrets FRONT_{cf_account}_CF_ACCOUNT_ID / _CF_API_TOKEN não existem.

Próximos passos

• Adicionar um novo environment — passo a passo completo
• Adicionar uma nova brand/fork
• Adicionar uma nova conta Cloudflare
• Referência de secrets e variáveis
• Cache, zonas e purge