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/api-client
  ├── @cactus-agents/auth
  ├── @cactus-agents/brand
  ├── @cactus-agents/types
  └── @cactus-agents/utils
          │
          │  publicados em https://npm.pkg.github.com
          │
          ▼
front-web-base + forks (consumidores)
  └── pnpm install → baixa do GitHub Packages

Por que não usamos GITHUB_TOKEN no CI​

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 extra5 pacotes × 30 forks = 150 configs manuais. Não escala.
PAT por repositórioSimplesAdicionar secret em cada fork. Manutenção por repo.
PAT como org secretUm secret, todos os repos herdamPAT atrelado a uma conta. Adotado.
Pacotes públicosZero authQualquer pessoa pode instalar os pacotes

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: All repositories

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

Diagrama​

┌─────────────────────────────┐
│  Org: cactus-agents         │
│                             │
│  Org Secret:                │
│  GH_PACKAGES_TOKEN = ghp_…  │
│        │                    │
│        ├──▶ front-web-base  │
│        ├──▶ front-web-vera  │
│        ├──▶ front-web-7k    │
│        └──▶ (todos os forks)│
└─────────────────────────────┘

Configuração local (desenvolvedores)​

.npmrc do projeto (commitado)​

Cada repo consumidor tem no .npmrc:

@cactus-agents:registry=https://npm.pkg.github.com

Isso redireciona @cactus-agents/* para o GitHub Packages. Não inclui token — a auth fica no ambiente.

Auth do desenvolvedor​

Cada dev configura um PAT pessoal no ~/.npmrc global:

//npm.pkg.github.com/:_authToken=ghp_SEU_TOKEN_AQUI

Para gerar:

  1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
  2. Escopo: read:packages
  3. Gerar e colar no ~/.npmrc
cuidado

Nunca commite tokens no repositório. O .npmrc do projeto contém apenas o registry, sem token.

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 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 fork criado​

Nenhuma ação extra para packages. O org secret GH_PACKAGES_TOKEN é herdado automaticamente.

Apenas configure os secrets específicos do fork:

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID

Revogar acesso de um desenvolvedor​

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

Fork saindo da org​

Se um fork precisar sair da org no futuro:

  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