CI/CD — GitHub Actions

Todos os repositórios da org cactus-agents usam GitHub Actions para CI e deploy.

Workflows por repositório

front-cactus-core (SDK)

Workflow	Trigger	O que faz
ci.yml	Push em main, PRs	Lint → Check → Build → Test
release.yml	Push em main (com changesets pendentes)	Build → Changesets (cria PR ou publica)

front-web-base (Template) e forks

Workflow	Trigger	O que faz
quality.yml	Push em main, PRs	Lint → Check → Typecheck → Test
deploy.yml	Push em main, workflow_dispatch	Chama reusable workflow do front-ops → Build → Deploy (Cloudflare Workers)

front-ops (Deploy centralizado)

Workflow	Trigger	O que faz
deploy.yml	workflow_call (chamado pelos forks)	Valida allowlist → Checkout fork → Build → Deploy no Cloudflare Workers

Modelo de deploy

O deploy segue um modelo caller + reusable workflow:

1. O fork tem um deploy.yml mínimo que chama cactus-agents/front-ops/.github/workflows/deploy.yml@main
2. O reusable workflow no front-ops lê config/allowlist.yml e valida o repo chamador
3. Resolve o worker_name correto para o environment solicitado
4. Faz checkout do código do fork, instala dependências, builda e deploya

# deploy.yml no fork (caller) — o fork só tem isso
jobs:
  deploy:
    uses: cactus-agents/front-ops/.github/workflows/deploy.yml@main
    with:
      environment: ${{ inputs.environment || 'production' }}
      ref: ${{ inputs.ref || github.sha }}
    secrets: inherit

O fork não contém lógica de resolução de worker name, tokens do Cloudflare ou pipeline de build/deploy.

Changesets (front-cactus-core)

O monorepo SDK usa @changesets/cli para versionamento e publicação automática dos pacotes @cactus-agents/*.

Fluxo

1. Dev cria changeset local:     pnpm changeset
2. Push em main com changeset → Actions cria PR "chore: version packages"
3. Merge do PR               → Actions publica no GitHub Packages

Criando um changeset

cd front-cactus-core
pnpm changeset
# Selecionar pacotes alterados
# Escolher bump type (patch / minor / major)
# Escrever descrição da mudança

O changeset é um arquivo .md em .changeset/ que deve ser commitado junto com a alteração.

Publicação

O workflow release.yml usa changesets/action@v1:

• Se existem changesets pendentes → cria/atualiza o PR "chore: version packages"
• Se o PR for mergeado (sem changesets pendentes) → executa pnpm run release que builda e publica

A publicação usa NODE_AUTH_TOKEN com GITHUB_TOKEN do próprio repositório (o core publica pacotes no seu próprio escopo, então o token padrão funciona).

Secrets

Org-level secrets (compartilhados por todos os repos)

Secret	Escopo do PAT	Uso
GH_PACKAGES_TOKEN	read:packages	Instalar @cactus-agents/* no CI dos forks (quality.yml)
FRONT_GH_ACTIONS_TOKEN	repo, read:packages	Checkout do front-ops (allowlist) + install de pacotes durante deploy
FRONT_CF_API_TOKEN	Cloudflare API	Deploy no Cloudflare Workers (via reusable workflow)
FRONT_CF_ACCOUNT_ID	Cloudflare API	Identificar a conta Cloudflare (via reusable workflow)

Separação de responsabilidades:

• GH_PACKAGES_TOKEN — usado apenas no CI dos forks (lint, test, typecheck). Scope mínimo: read:packages
• FRONT_GH_ACTIONS_TOKEN — usado pelo reusable workflow de deploy. Precisa de repo (para checkout do front-ops privado) e read:packages (para instalar pacotes)
• FRONT_CF_* — tokens do Cloudflare, usados apenas no step de deploy

Permissões dos workflows

Os workflows devem declarar o bloco permissions explicitamente:

jobs:
  quality:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read

Sem esse bloco, o GITHUB_TOKEN recebe permissões padrão que podem não incluir packages: read.

Adicionando CI/CD a um novo fork

Ao criar um fork de front-web-base, os workflows já vêm incluídos. Basta:

1. Garantir que o repo esteja na allowlist do front-ops (config/allowlist.yml)
2. Configurar acesso aos org secrets de deploy para o novo repo
3. O GH_PACKAGES_TOKEN já está disponível via org secret
4. Push em main → workflows rodam automaticamente