Pular para o conteúdo principal

GitHub Packages — Registry Privado

Os pacotes @cactus-agents/* são publicados no GitHub Packages como registry npm privado.

Visão geral​

front-cactus-core (SDK)
  ├── @cactus-agents/accounts
  ├── @cactus-agents/api-client
  ├── @cactus-agents/brand
  ├── @cactus-agents/games
  ├── @cactus-agents/i18n
  ├── … (16 pacotes hoje — lista viva em packages/)
          │
          │  publicados em https://npm.pkg.github.com
          │
          ▼
consumidores
  └── front-web-base
          └── pnpm install → baixa do GitHub Packages

É um repo consumidor, não uma frota de forks. front-web-7k e front-web-state77 não existem — prod-7k-bet-br e state77-com são environments, não repos.

:::caution Pacotes que não existem mais @cactus-agents/auth, @cactus-agents/user e @cactus-agents/wallet foram removidos e unificados em @cactus-agents/accounts. @cactus-agents/mocks ainda existe publicado mas está deprecado (stubs vazios) e não é mais dependência do front-web-base — foi removido do package.json dele. E @cactus-agents/sports-rogue é uma dependência real do base que não é publicada pelo front-cactus-core — ela vem de outro lugar.

A lista viva é repos/front-cactus-core/packages/. :::

Por que não usamos GITHUB_TOKEN no CI dos consumidores​

O GITHUB_TOKEN automático do GitHub Actions é limitado ao repositório onde o workflow roda. Quando o CI do front-web-base tenta baixar pacotes publicados pelo front-cactus-core, o token não tem permissão — resulta em 403 Forbidden.

Alternativas avaliadas:

AbordagemPrósContras
Conceder acesso por pacoteSem PAT extra16 pacotes × cada repo consumidor = matriz manual que cresce a cada pacote novo. Não escala
PAT por repositórioSimplesAdicionar secret em cada repo. Manutenção por repo
PAT como org secretUm secret, os repos autorizados herdamPAT atrelado a uma conta. Adotado
Pacotes públicosZero authQualquer pessoa pode instalar os pacotes

:::info No core é diferente O publish usa o GITHUB_TOKEN do próprio repositório (NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} no ci-release.yml), porque o core publica no próprio escopo. O front-cactus-core não tem .npmrc — o actions/setup-node com registry-url resolve a auth. O PAT existe só para o lado do consumo. :::

Estratégia adotada: org secret​

Um único PAT (classic) com escopo read:packages, armazenado como org secret na organização cactus-agents.

Configuração​

  1. PAT: Settings → Developer settings → Personal access tokens → Tokens (classic)

    • Escopo: read:packages
    • Nome sugerido: org-packages-read

  2. Org secret: GitHub → cactus-agents → Settings → Secrets and variables → Actions

    • Nome: GH_PACKAGES_TOKEN
    • Valor: o PAT gerado
    • Repository access: selected repositories — adicione cada repo que precisa instalar os pacotes

  3. Workflows: usam ${{ secrets.GH_PACKAGES_TOKEN }} como NODE_AUTH_TOKEN

Diagrama​

┌───────────────────────────────────┐
│  Org: cactus-agents               │
│                                   │
│  Org Secret: GH_PACKAGES_TOKEN    │
│  (Repository access: selected)    │
│        │                          │
│        ├──▶ front-web-base        │
│        └──▶ (futuros consumidores)│
└───────────────────────────────────┘

Configuração local (desenvolvedores)​

O token do dev vai num .npmrc local ao projeto, não no ~/.npmrc global. É o que o setup.sh do workspace faz automaticamente:

# repos/front-web-base/.npmrc   (gitignored)
@cactus-agents:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<seu-PAT-com-read:packages>

Passo a passo (gerar o PAT, rodar o setup) em Contributing → Setup.

:::caution Não use ~/.npmrc global Colocar o token no ~/.npmrc global expõe ele para todo projeto na máquina. O .npmrc do projeto está no .gitignore e limita o alcance. :::

Manutenção​

PAT expirou​

  1. Gerar novo PAT com read:packages
  2. Atualizar o org secret GH_PACKAGES_TOKEN (Org Settings → Secrets → Actions)
  3. Todos os repos autorizados são corrigidos automaticamente — não é necessário alterar nada nos workflows

Novo pacote @cactus-agents/*​

Nenhuma ação extra. O PAT tem acesso a todos os pacotes da org cactus-agents.

Novo repo consumidor​

As org secrets têm acesso restrito a repos selecionados. Ao criar um novo repo:

  1. GitHub → cactus-agents → Settings → Secrets and variables → Actions
  2. Editar GH_PACKAGES_TOKEN → adicionar o novo repo no Repository access
  3. Editar FRONT_GH_ACTIONS_TOKEN → adicionar o novo repo no Repository access
  4. Editar FRONT_{XX}_CF_ACCOUNT_ID e FRONT_{XX}_CF_API_TOKEN da conta CF utilizada → adicionar o novo repo

Além disso, o repo deve estar declarado em front-ops/config/brands/<brand>/brand.yml (campo repo:) com pelo menos um environment. Ver Deploy → Adicionar brand/fork.

Se a brand usa um domínio novo, editar também o API Token na conta CF para incluir a nova zona em Zone Resources.

Revogar acesso de um desenvolvedor​

Remover da org cactus-agents. O PAT pessoal do dev para de funcionar automaticamente.

Repo consumidor saindo da org​

  1. Criar um PAT de serviço dedicado com read:packages
  2. Adicionar como secret no repo externo
  3. O PAT pode ser revogado individualmente a qualquer momento