Adicionar uma nova brand / fork

Hoje o stack consolida as marcas em um único template multi-país (front-web-base), servindo cada marca 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 um repo fork) somente quando o cliente precisar divergir de forma estrutural do template (código próprio, páginas exclusivas), 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 -.

Existe uma brand hoje:

Brand	Repo	Envs
web-base	cactus-agents/front-web-base	o template multi-país (28 envs)

:::caution Marca ≠ brand prod-7k-bet-br e state77-com não são brands — são environments da brand web-base. Não existe config/brands/state77-com/. Confundir os dois níveis é o erro mais comum ao ler estes configs. :::

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, lighthouse.yml, delete-merged-branch.yml).

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 em Adicionar environment.

4 — Ajustar o ci-deploy.yml do fork

Duas coisas:

1. Dropdown de environments — o fork precisa ter os envs da própria brand em on.workflow_dispatch.inputs.environment.options.

2. Diretório da brand — no front-web-base, o job config-lint fixa no shell do step:

   BRAND_DIR="_ops/config/brands/web-base"
   CALLER="cactus-agents/front-web-base"

   No fork esses dois valores têm que apontar para a brand e o repo do fork, senão a checagem de ownership falha.

:::caution Confirme no fork Os jobs resolve-matrix e list-environments do front-web-base fazem o próprio scan de config/brands/web-base/environments — a brand está hardcoded neles. Num fork esses jobs precisam apontar para a pasta da brand do fork. Trate o passo acima como o padrão do web-base e ajuste no fork antes de aplicar. :::

5 — Acesso das org secrets (GitHub)

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 nos bindings, CF_WORKER_KEY na org secret e no Worker, 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

:::danger Fork se atualiza por cherry-pick, NUNCA por merge do base Um fork é um snapshot de um ponto do front-web-base, não um branch que acompanha o base. Mergear o base no fork arrasta as outras marcas, os overrides delas e mudanças estruturais que o fork deliberadamente não tem.

Regra: para levar uma mudança do base para o fork, faça git cherry-pick <sha> do commit específico. Nunca git merge origin/main (nem main-*) vindo do base. :::

Atualizar os pacotes de plataforma é seguro e não gera conflito estrutural:

pnpm update "@cactus-agents/*" --latest

Não há nenhum fork ativo hoje — todas as marcas em produção são brand overrides dentro do web-base. Esta página descreve o caminho pro dia em que um fork for inevitável.

Para as regras de override de arquivos por marca (que são o mecanismo preferido a um fork), ver Fork de Marca → Guia.