Token Composer nella CI: GitHub Actions e GitLab CI

Una pipeline deve installare i pacchetti senza che nessuno digiti credenziali, e senza che il token finisca nel repository o in un log di build. Composer legge le credenziali dalla variabile d’ambiente COMPOSER_AUTH, e i sistemi di CI passano i segreti ai job come variabili d’ambiente. Questa guida collega le due cose e limita ciò che un token trapelato potrebbe fare.

Passo 1 — Crea un token per la pipeline#

Per un progetto di team, crea un token dell’organizzazione (la tua organizzazione → Token Composer): appartiene al team e continua a funzionare quando le persone se ne vanno. Per un progetto personale basta un token personale (Impostazioni → Token Composer).

Limita il token quando lo crei:

• Pacchetti — solo i nomi Composer usati dal progetto. Un pattern come meteorgpl-plugin/* consente tutti i plugin.
• Reti — solo gli intervalli IP usati dai tuoi runner. È adatto ai runner self-hosted con indirizzi fissi; lascia il campo vuoto per i runner ospitati, i cui indirizzi cambiano.
• Scadenza — la data in cui il token smette di funzionare. Ricevi una notifica quando uno dei tuoi token scade entro sette giorni.

Copia il token quando viene mostrato: viene mostrato una sola volta.

Passo 2 — Salvalo come segreto#

Dai al segreto il nome METEORGPL_TOKEN in entrambi i sistemi:

• GitHub: nel repository, Settings → Secrets and variables → Actions → New repository secret.
• GitLab: nel progetto, Settings → CI/CD → Variables. Contrassegna la variabile come masked e, se solo i branch protetti installano pacchetti, anche come protected.

Passo 3 — GitHub Actions#

COMPOSER_AUTH contiene lo stesso JSON di un file auth.json. Il nome utente è letteralmente la parola token; la password proviene dal segreto:

name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'

      - name: Composer cache directory
        id: composer-cache
        run: echo "dir=$(composer config cache-dir)" >> "$GITHUB_OUTPUT"

      - uses: actions/cache@v4
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          key: composer-${{ hashFiles('composer.lock') }}
          restore-keys: composer-

      - name: Install PHP dependencies
        env:
          COMPOSER_AUTH: '{"http-basic":{"composer.meteorgpl.ddev.site":{"username":"token","password":"${{ secrets.METEORGPL_TOKEN }}"}}}'
        run: composer install --no-interaction --prefer-dist

Una volta pubblicati, i dist non cambiano mai, quindi è sicuro conservare la cache tra un’esecuzione e l’altra; la sua chiave dipende da composer.lock, quindi un nuovo file lock avvia una cache nuova.

Passo 4 — GitLab CI#

GitLab espande $METEORGPL_TOKEN all’interno del valore della variabile. GitLab mette in cache solo percorsi all’interno della directory del progetto, quindi indirizza lì la cache di Composer:

install:
  image: composer:2
  variables:
    COMPOSER_AUTH: '{"http-basic":{"composer.meteorgpl.ddev.site":{"username":"token","password":"$METEORGPL_TOKEN"}}}'
    COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"
  cache:
    key:
      files:
        - composer.lock
    paths:
      - .composer-cache/
  script:
    - composer install --no-interaction --prefer-dist

Bitbucket Pipelines e CircleCI funzionano allo stesso modo; la documentazione sulla CI contiene i relativi snippet.

Passo 5 — Invia il file lock (facoltativo)#

La dashboard delle dipendenze confronta il composer.lock di un sito con il repository e mostra ogni pacchetto come aggiornato, non aggiornato (con le voci del changelog che ti mancano), ritirato o rimosso. Crea un progetto in Impostazioni → Progetti (o tra i Progetti della tua organizzazione), poi lascia che la pipeline carichi il file lock dopo ogni build del branch principale:

      - name: Report composer.lock to the dependency dashboard
        if: github.ref == 'refs/heads/main'
        run: curl -fsS -u "token:${{ secrets.METEORGPL_TOKEN }}" -F [email protected] https://meteorgpl.ddev.site/api/projects/<project-id>/lock

Il token deve appartenere all’account o all’organizzazione proprietaria del progetto.

Tieni il token al riparo#

• Non stampare mai COMPOSER_AUTH né il segreto. GitHub maschera i segreti nei log e GitLab maschera le variabili masked, ma solo nelle forme che riconoscono.
• Non eseguire mai il commit di un auth.json. Con COMPOSER_AUTH non c’è alcun file di cui fare il commit.
• Ruota il token senza interruzioni: crea il nuovo token, aggiorna il segreto, esegui la pipeline, revoca il vecchio token.
• Un token usato da molte reti diverse nello stesso giorno viene considerato condiviso: ricevi un avviso, e un token chiaramente trapelato viene revocato automaticamente.

Risoluzione dei problemi#

• 401 Unauthorized — il segreto manca, è scritto male, è scaduto o è stato revocato. Su GitHub, i workflow avviati da pull request provenienti da fork non ricevono i segreti del repository.
• 403 Forbidden — il token è valido, ma l’account o l’organizzazione a cui appartiene non ha accesso al repository, oppure i limiti del token su pacchetti o reti escludono questa richiesta.
• Composer chiede un nome utente — l’host in COMPOSER_AUTH deve essere esattamente composer.meteorgpl.ddev.site: niente https://, niente percorso.