Pular para o conteúdo principal

Adicionar uma nova brand / fork

Hoje o stack consolida todas as marcas em um único template multi-país (front-web-base), servindo cada brand por environment (Worker + domínio). Para a maioria dos casos novos, você não cria um fork — apenas adiciona um novo environment na brand web-base.

Crie uma brand separada (e eventualmente um repo fork) somente quando o cliente precisar divergir de forma estrutural do template (código próprio, páginas exclusivas, etc.), a ponto de justificar um repositório independente.

:::tip Na dúvida Se é só "mais um país/marca servido pelo mesmo template" → use um environment em web-base. Se é "um repo com código próprio do cliente" → siga este guia. :::

Convenção: uma brand = um repo​

Cada brand vive em front-ops/config/brands/<brand>/ e o campo repo: no brand.yml declara qual repositório git pertence a ela. Dois brand.yml não podem declarar o mesmo repo: (o reusable workflow falha com erro de conflito).

Regras do nome da pasta <brand>:

  • kebab-case, só letras minúsculas, números e -
  • exemplos: web-base, vera-bet-br, cassino-bet-br

Passo a passo​

1 — Criar o repositório fork​

Clone/forke o front-web-base como front-web-<marca> na org cactus-agents. O fork já vem com os workflows (ci-deploy.yml, list-environments.yml, etc).

2 — Criar a brand no front-ops​

# front-ops/config/brands/<marca>/brand.yml
brand: <marca>
repo: cactus-agents/front-web-<marca>

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

:::info Placeholder Uma brand sem repo: é tratada como placeholder (fork ainda não criado) e é ignorada pelo reusable workflow. Você pode commitar o brand.yml sem repo: e preencher depois. :::

3 — Criar o primeiro environment​

# front-ops/config/brands/<marca>/environments/<env>/deploy.yml
worker_name: front-web-<marca>
cf_account: CT
auto_deploy: false
default_branch: main
language: pt-br
origin_domain: <marca>.com
worker_url: <marca>.com
cf_zone: <marca>.com

Detalhes de cada campo e variantes (stage/subdomínio/auto-deploy) em Adicionar environment.

4 — Ajustar o dropdown do fork​

No fork, o ci-deploy.yml precisa ter o(s) environment(s) da brand no dropdown de workflow_dispatch (o config-lint valida sync com o front-ops). Como o fork tem seu próprio scan (config/brands/<marca>/environments), ajuste o brand-dir referenciado nos jobs config-lint / resolve-matrix / list-environments se necessário (no web-base é web-base; no fork deve apontar para <marca>).

5 — Acesso das org secrets (GitHub)​

As org secrets têm acesso restrito a repos selecionados. Edite cada secret e adicione o novo repo em Repository access:

  • GH_PACKAGES_TOKEN — para o CI (instalar @cactus-agents/*)
  • FRONT_GH_ACTIONS_TOKEN — para o deploy (checkout do front-ops + install)
  • FRONT_{XX}_CF_ACCOUNT_ID / FRONT_{XX}_CF_API_TOKEN — conta CF da brand
  • (se aplicável) FRONT_{XX}_CACHE_PURGE_SECRET, FRONT_{XX}_CF_WORKER_KEY, FRONT_{XX}_R2_ASSETS_ACCESS_KEY, FRONT_{XX}_R2_ASSETS_SECRET

Ver Referência de secrets.

6 — Zona no token CF​

Se a brand usa um domínio novo, edite o FRONT_{XX}_CF_API_TOKEN no Cloudflare Dashboard e inclua a nova zona em Zone Resources. Ver Adicionar conta CF.

7 — Subir o Worker e configurar vars/secrets​

Siga a Parte 3 do guia de environment: primeiro deploy, API_BASE_URL/CF_WORKER_KEY nos bindings, DNS/route.

8 — Validar​

Dispare o deploy manual (Actions → CI/CD → Run workflow → selecione o env) e confira o Summary. Ver validação.

Manutenção do fork​

# Atualizar a lógica de plataforma (pacotes do core) — sem merge conflicts
pnpm update @cactus-agents/*

Para propagar mudanças de UI/estrutura do front-web-base, um PR script pode ser usado; a superfície de conflito depende de quanto o fork divergiu do base. Ver Fork de Marca → Guia.