Adicionar um novo environment (setup)

Guia passo a passo para colocar um novo environment (setup) no ar — desde a config versionada no front-ops até subir o Worker e configurar as variáveis externas no Cloudflare.

Um "environment" aqui é um deploy alvo: uma combinação de Worker + domínio + branch + conta CF. Exemplos reais: prod-7k-bet-br, stage-7k-bet-br-cactusgaming-tech, dev-state77-com-bluetec-live.

:::info Pré-requisitos

A brand já existe em front-ops/config/brands/<brand>/ com repo: apontando para o repo certo. Se ainda não existe, faça primeiro o Adicionar brand/fork.
A conta Cloudflare (cf_account) já está cadastrada. Se for uma conta nova, faça primeiro o Adicionar conta CF.
Você tem acesso ao Cloudflare Dashboard da conta alvo e permissão para editar as org secrets no GitHub (ou alguém que tenha). :::

Visão geral das 5 partes

front-ops      → criar environments/<env>/deploy.yml
front-web-base → adicionar <env> no dropdown do ci-deploy.yml
Cloudflare     → subir o Worker (1º deploy) e configurar vars/secrets
GitHub/CF      → garantir acesso das org secrets + zona no token
Validar        → dispatch manual e conferir

A ordem importa: o passo 3 (vars no Worker) precisa estar pronto antes do deploy automatizado conseguir ler API_BASE_URL/CF_WORKER_KEY dos bindings.

Parte 1 — front-ops: criar o environment

Crie a pasta e o deploy.yml do novo env:

front-ops/config/brands/web-base/environments/<env>/deploy.yml

O nome da pasta <env> é o id do environment — é o que vai no dropdown e no scan de auto-deploy. Use kebab-case.

Exemplo: environment de produção

# config/brands/web-base/environments/prod-minha-marca-com/deploy.yml
worker_name: front-web-minha-marca-com
cf_account: CT
auto_deploy: false
default_branch: main
language: pt-br
origin_domain: minha-marca.com
worker_url: minha-marca.com
cf_zone: minha-marca.com

# Produção: trava deploy manual no time de deployers
deploy_protection:
  required_team: rulesets-groups-front-deployers-cactus-agents-front-web-base-reader

Exemplo: environment de staging (subdomínio)

# config/brands/web-base/environments/stage-minha-marca-cactusgaming-tech/deploy.yml
worker_name: front-web-stage-minha-marca-cactusgaming-tech
cf_account: CT
auto_deploy: true
default_branch: stage
language: pt-br
origin_domain: minha-marca.com
# worker_url é um subdomínio; cf_zone aponta para a zona apex real onde o
# worker é servido (senão o purge SSR pós-deploy não encontra a zona).
worker_url: stage-minha-marca.cactusgaming.tech
cf_zone: cactusgaming.tech

:::caution cf_zone em subdomínios Quando worker_url/origin_domain é um subdomínio de uma zona diferente, declare cf_zone explicitamente apontando para a zona apex que existe na Cloudflare. Sem isso, o purge SSR pós-deploy é pulado silenciosamente. Detalhes em Cache & Purge. :::

Regras de preenchimento

Decisão	Como escolher
`auto_deploy`	`true` para stage/dev que deployam automático no push do branch; `false` para prod (deploy manual controlado).
`default_branch`	O branch que será deployado neste env (`main`, `stage`, `dev`, `performance`, `sports`, ou variantes `*-<sufixo>`).
`cf_account`	A conta CF onde o domínio vive (`CT`/`BT`/`TS`). Tem que bater com a zona no token.
`cf_zone`	Apex zone na CF. Apex (`marca.com`) resolve sozinho; subdomínio precisa explícito.
`deploy_protection`	Só em produção / envs sensíveis.

:::tip Branch nova Se o default_branch for um padrão de branch ainda não coberto pelos filtros do caller (main, main-*, stage, stage-*, dev, dev-*, performance, performance-*, sports, sports-*), você precisa adicionar o glob em on.push.branches e on.pull_request.branches do ci-deploy.yml. O job config-lint falha a PR se faltar cobertura. :::

O caller ci-deploy.yml tem uma lista estática de environments no dropdown de workflow_dispatch. O job config-lint exige que essa lista bata exatamente com as pastas em front-ops/.../environments/ — drift quebra a PR.

Edite front-web-base/.github/workflows/ci-deploy.yml e adicione o novo <env> em on.workflow_dispatch.inputs.environment.options (mantenha ordenado para facilitar o diff):

on:
  workflow_dispatch:
    inputs:
      environment:
        description: "Target environment"
        type: choice
        default: react-casateste-com
        options:
          - ...
          - prod-minha-marca-com          # ← novo
          - stage-minha-marca-cactusgaming-tech  # ← novo
          - ...

:::info Por que duplicar a lista? A lista no dropdown é estática porque o GitHub não resolve choice options em runtime. O front-ops continua sendo a fonte de verdade — o config-lint apenas garante que o dropdown não fique dessincronizado. Adicionar/remover env = editar o front-ops e o dropdown. :::

Parte 3 — Cloudflare: subir o Worker e configurar variáveis

Esta é a parte "externa". O Worker precisa existir e ter as vars/secrets configuradas antes do primeiro deploy automatizado, porque o reusable workflow lê API_BASE_URL e CF_WORKER_KEY dos bindings do Worker já existente (step "Resolve API_BASE_URL and CF_WORKER_KEY"). Num Worker que nunca subiu, esses bindings não existem e o build sai sem API_BASE_URL.

3.1 — Primeiro deploy (criar o Worker)

O Worker é criado no primeiro wrangler deploy --name <worker_name>. Há duas formas:

Opção A — pelo pipeline (recomendado): dispare o deploy manual uma primeira vez (Parte 5). O wrangler deploy --name <worker_name> cria o Worker automaticamente. Como API_BASE_URL ainda não existe nos bindings, esse primeiro build sai sem ela (::warning::API_BASE_URL not found) — isso é esperado. Depois configure as vars (3.2) e rode o deploy de novo.

Opção B — manualmente, localmente: a partir do front-web-base, com as credenciais da conta CF:

CLOUDFLARE_ACCOUNT_ID=<account-id-da-conta> \
CLOUDFLARE_API_TOKEN=<token-da-conta> \
npx wrangler deploy --name front-web-minha-marca-com

Isso cria o Worker placeholder. Em seguida configure as vars/secrets.

3.2 — Configurar variáveis e secrets no Worker

No Cloudflare Dashboard → Workers & Pages → <worker_name> → Settings → Variables and Secrets (ou via wrangler), configure:

Plain text vars (lidas pelo pipeline e/ou runtime)

Variável	Tipo	Obrigatória	Descrição
`API_BASE_URL`	Plain	✅	URL base da API/BFF (ex: `https://api.minha-marca.com/v2`). Lida pelo pipeline para injetar no build.
`BRAND_COUNTRY`	Plain	✅	`BRA`, `CHL`, `MEX`, `PER`, `NGA`, etc.
`BRAND_CURRENCY`	Plain	✅	`BRL`, `CLP`, `MXN`, `PEN`, `NGN`, etc.
`BRAND_TIMEZONE`	Plain	recomendado	Timezone da marca (server-only). Ex: `America/Sao_Paulo`.
`CASSINO_MODE`	Plain	opcional	`legacy` (default) ou `api_new`.
`FORCE_SPORTBOOK`	Plain	opcional	`first`/`altenar`/`betby`/`rogue` — override de sportbook por env.
`STICKER_API_URL`	Plain	opcional	URL do BFF de sticker-album (gamification).
`TURNSTILE_SITE_KEY` / `RECAPTCHA_SITE_KEY`	Plain	opcional	Site keys públicas de captcha.

Secrets (`wrangler secret put` ou marcados como "Secret" no dashboard)

Secret	Obrigatório	Descrição
`CF_WORKER_KEY`	recomendado	Chave Worker→BFF (header `cf-worker-key`, WAF bypass). Também lida pelo pipeline.
`SMARTICO_SALT_KEY`	se usa gamification Smartico	Salt para hash de auth Smartico.
`SPORTS_ROGUE_API_KEY`	se `FORCE_SPORTBOOK=rogue`	Header `x-api-key` server-to-server p/ tokens do sportbook Rogue.

:::caution Não confunda as duas pontas

BRAND_LANGUAGE, ORIGIN_DOMAIN e GITHUB_SHA são injetados pelo front-ops no build (vêm do deploy.yml), não precisa configurar no Worker.
BUILD_ID, WORKER_NAME, PLATFORM_CACHE_POLICY_JSON, CACHE_NAMESPACE e o binding PLATFORM_CACHE_KV são injetados pelo front-ops via patch do wrangler.toml no deploy — não configure à mão (são sobrescritos).
API_BASE_URL e CF_WORKER_KEY precisam existir nos bindings do Worker porque o pipeline os lê de lá. Configure no dashboard/wrangler. :::

A lista completa de variáveis está em Referência de secrets e no doc do template Environment Variables.

3.3 — DNS / rota do domínio

Garanta que o domínio (worker_url) aponta para o Worker:

No Cloudflare, o domínio precisa estar na conta (cf_account) como zona.
Configure o Worker Route ou Custom Domain apontando o hostname (worker_url) para o <worker_name>.

Parte 4 — Acesso de secrets e zona do token

Garanta que o repo caller tem acesso às org secrets e que o token CF cobre a zona.

Org secrets (GitHub → cactus-agents → Settings → Secrets and variables → Actions): o repo precisa estar no Repository access de cada secret relevante. Se a brand/repo já deployava antes, isso já está OK; só confira se está usando uma cf_account nova.
CF API Token — Zone Resources: o FRONT_{cf_account}_CF_API_TOKEN precisa incluir a zona apex (cf_zone) em Zone Resources. Sem isso, o purge SSR pós-deploy retorna 401/403. Ver Adicionar conta CF e Cache & Purge.

Parte 5 — Validar o deploy

Conferir a topologia

No GitHub Actions do front-web-base, dispare o workflow List environments (somente leitura) — ele renderiza uma tabela por branch com URL, conta CF e status de auto-deploy. Confirme que seu env aparece.

Disparar o deploy manual

Actions → CI/CD → Run workflow:

Use workflow from: pode deixar o default — não afeta o código deployado.
Target environment: selecione o novo <env>.

O reusable resolve o HEAD do default_branch, builda e publica. Acompanhe o Summary do run (brand, env, conta CF, URL, ref, cache).

Auto-deploy (se `auto_deploy: true`)

Um push no default_branch dispara o deploy automaticamente. A matriz só inclui envs cujo default_branch == branch empurrado e auto_deploy: true.

Checklist final

front-ops/.../environments/<env>/deploy.yml criado e mergeado em main
<env> adicionado no dropdown do ci-deploy.yml (PR passou no config-lint)
Worker existe na CF com API_BASE_URL (e CF_WORKER_KEY) configurados
Demais vars/secrets do Worker configuradas conforme a brand
DNS/route do worker_url apontando para o Worker
Org secrets dão acesso ao repo; token CF cobre a zona (cf_zone)
Deploy manual rodou verde; site carrega; cache/purge sem warnings críticos

Troubleshooting

Sintoma	Causa provável	Correção
`::warning::API_BASE_URL not found in Cloudflare bindings`	Worker não tem `API_BASE_URL` nos bindings	Configurar `API_BASE_URL` no Worker (Parte 3.2) e redeployar
`Environment '<env>' not found`	`deploy.yml` ausente ou nome de pasta diferente do dropdown	Conferir nome da pasta vs option do dropdown
`config-lint` falha na PR	Dropdown dessincronizado do `front-ops`	Sincronizar lista de options com as pastas de environments
`cf_account ... is invalid`	`cf_account` não é 2-4 letras maiúsculas	Usar `CT`/`BT`/`TS`
`CF credentials not found for account`	Org secrets da conta ausentes / sem acesso ao repo	Criar/dar acesso a `FRONT_{XX}_CF_ACCOUNT_ID` e `_CF_API_TOKEN`
`SSR cache purge skipped` / 401 no purge	`cf_zone` errado ou zona fora do Zone Resources do token	Declarar `cf_zone` apex e incluir a zona no token
`Could not resolve HEAD SHA of '<branch>'`	`default_branch` não existe no repo, ou token sem acesso	Criar o branch / revisar `FRONT_GH_ACTIONS_TOKEN`
`Actor ... is NOT in '@cactus-agents/<team>'`	`deploy_protection` ativo e usuário fora do team	Pedir entrada no team ou disparar por quem é membro

Visão geral das 5 partes​

Parte 1 — front-ops: criar o environment​

Exemplo: environment de produção​

Exemplo: environment de staging (subdomínio)​

Regras de preenchimento​

Parte 2 — front-web-base: registrar no dropdown​

Parte 3 — Cloudflare: subir o Worker e configurar variáveis​

3.1 — Primeiro deploy (criar o Worker)​

3.2 — Configurar variáveis e secrets no Worker​

Plain text vars (lidas pelo pipeline e/ou runtime)​

Secrets (wrangler secret put ou marcados como "Secret" no dashboard)​

3.3 — DNS / rota do domínio​

Parte 4 — Acesso de secrets e zona do token​

Parte 5 — Validar o deploy​

Conferir a topologia​

Disparar o deploy manual​

Auto-deploy (se auto_deploy: true)​

Checklist final​

Troubleshooting​