Configurazione GitHub Packages

Panoramica

Il progetto elerama-frontend utilizza pacchetti privati pubblicati su GitHub Packages:

• @elerama/ui - Componenti UI condivisi
• @elerama/icons - Icone SVG

Per installare questi pacchetti, è necessario autenticarsi con un token GitHub.

Setup Locale

Prerequisiti

• Account GitHub con accesso all'organizzazione elerama
• Node.js e npm installati

Procedura

Step 1: Genera un Personal Access Token

1. Vai su https://github.com/settings/tokens
2. Clicca "Generate new token" → "Generate new token (classic)"
3. Configura il token:
   • Note: npm-elerama-frontend (nome descrittivo)
   • Expiration: 90 days (raccomandato per sicurezza)
   • Scopes: seleziona SOLO read:packages
4. Clicca "Generate token"
5. IMPORTANTE: Copia subito il token - non sarà più visibile!

Step 2: Configura .npmrc locale

# Dalla root del progetto
cp .npmrc.example .npmrc

Apri .npmrc e sostituisci YOUR_GITHUB_TOKEN_HERE con il token copiato:

@elerama:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=ghp_tuoTokenQuiABC123xyz

Step 3: Verifica

npm install

Se vedi errori 401 o 403, verifica:

• Il token ha lo scope read:packages
• Il token non è scaduto
• Hai accesso all'organizzazione elerama

CI/CD

In GitHub Actions, il setup è automatico. Il workflow deploy.yml usa:

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    registry-url: "https://npm.pkg.github.com"
    scope: "@elerama"

- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

setup-node@v4 crea automaticamente un .npmrc con il token GITHUB_TOKEN (disponibile di default in ogni workflow).

Sicurezza

Token Scopes

Usa SEMPRE lo scope minimo necessario:

• ✅ read:packages - Sufficiente per npm install
• ❌ write:packages - NON usare a meno che non devi pubblicare pacchetti

Rotazione Token

Rigenera il token ogni 90 giorni o quando:

• Sospetti una compromissione
• Un membro del team lascia il progetto
• Cambi macchina di sviluppo

Cosa Fare se Committi un Token

Se accidentalmente committi un token:

1. REVOCA IMMEDIATAMENTE il token su GitHub:

   • Vai su https://github.com/settings/tokens
   • Trova il token e clicca "Delete"

2. Genera un nuovo token seguendo la procedura sopra

3. Avvisa il team - Il token potrebbe essere ancora presente negli altri clone locali

4. Considera di ripulire la git history usando git filter-branch o BFG Repo-Cleaner (chiedi al team lead)

Troubleshooting

Errore 401 Unauthorized

npm error code E401
npm error Unable to authenticate

Cause:

• Token mancante o errato in .npmrc
• Token scaduto
• File .npmrc non presente

Soluzione: Rigenera il token e riconfigura .npmrc.

Errore 403 Forbidden

npm error code E403
npm error 403 Forbidden - GET https://npm.pkg.github.com/@elerama/ui

Cause:

• Token senza scope read:packages
• Non hai accesso all'organizzazione elerama

Soluzione: Verifica gli scope del token e l'accesso all'organizzazione.

npm ci fallisce in CI ma npm install funziona localmente

Verifica che:

• Il workflow usa NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
• Il repository ha accesso ai pacchetti dell'organizzazione
• Il workflow ha il permesso packages: read nelle sue permissions

File .npmrc non trovato dopo git pull

Questo è normale - .npmrc è ignorato da git per sicurezza. Se hai già un .npmrc funzionante, continua a usarlo. Altrimenti:

cp .npmrc.example .npmrc
# Aggiungi il tuo token

Note Aggiuntive

Differenza tra .npmrc e .npmrc.local

• .npmrc: Ignorato da git, puoi usarlo per la configurazione locale
• .npmrc.local: Anche ignorato da git, alternativa se preferisci mantenere .npmrc per altre configurazioni

Entrambi funzionano allo stesso modo - usa quello che preferisci.

Alternative: Configurazione globale

Puoi configurare l'autenticazione anche a livello globale (~/.npmrc), ma NON è raccomandato perché:

• Il token sarà usato per tutti i progetti npm sulla tua macchina
• Difficile gestire token diversi per organizzazioni diverse
• Maggiore rischio di sicurezza se il token ha scope troppo ampi

Raccomandazione: Usa sempre la configurazione locale al progetto.