Automatizza la pubblicazione dei flipbook in CI/CD con la FlipLink CLI

Se un PDF vive nel tuo repository — le note di rilascio, un catalogo prodotti, un report trimestrale — allora pubblicarne la versione flipbook dovrebbe far parte della stessa build che produce il PDF. Niente dashboard, niente upload manuale, niente "qualcuno si è ricordato di aggiornare il flipbook?". La FlipLink CLI è pensata esattamente per questo: gira in modalità headless, si autentica da una variabile d'ambiente e restituisce exit code puliti su cui una pipeline può ramificarsi.

Questa guida mostra una pipeline CI/CD minima e indipendente dalla piattaforma che costruisce un PDF, crea il flipbook, lo pubblica e cattura l'URL pubblico.

Perché eseguire la pubblicazione in CI

La dashboard è perfetta per gli upload occasionali. Una pipeline è la scelta migliore quando il lavoro è ripetibile:

• Ripetibile e tracciabile — gli stessi passaggi vengono eseguiti ogni volta, registrati nella cronologia della tua CI.
• Niente dashboard, niente intervento umano — nessuno deve ricordarsi di caricare il file dopo un rilascio.
• Un'unica fonte di verità — il PDF nel repository è ciò che viene spedito, così il flipbook non si scosta mai dal documento.
• Errori in chiaro — se una pubblicazione si rompe, la build diventa rossa invece di spedire in silenzio un flipbook obsoleto.

Questa è automazione nel senso più semplice del termine: la CLI usa lo stesso motore dell'API, quindi tutto ciò che puoi fare a mano puoi metterlo in uno script.

Passo 1: salva la chiave API come segreto della CI

La CLI legge la tua chiave dalla variabile d'ambiente FLIPLINK_API_KEY in CI (l'ordine di risoluzione è variabile d'ambiente → file di configurazione → valore predefinito). Ottieni una chiave accedendo a go.fliplink.me e aprendo la pagina Subscription.

Aggiungila come segreto presso il tuo provider CI — non committarla mai, non stamparla mai nei log. Poi rendila disponibile al job come variabile d'ambiente:

# Provided by your CI's secret store, not hard-coded
export FLIPLINK_API_KEY="$CI_SECRET_FLIPLINK_API_KEY"

Una rapida verifica che l'autenticazione funzioni prima di passare al lavoro vero:

fliplink whoami

Se la chiave manca o è errata, il comando termina con un valore diverso da zero e la tua pipeline si ferma subito — esattamente quello che vuoi.

Passo 2: una pipeline minima

Ecco una pipeline generica e indipendente dalla piattaforma (pseudo-YAML — mappa le chiavi sulla CI che usi). Per una versione GitHub Actions specifica, attivata dal rilascio, vedi la guida GitHub Actions al rilascio.

pipeline:
  publish-flipbook:
    image: node:20
    secrets:
      - FLIPLINK_API_KEY        # injected from the CI secret store
    steps:
      - name: Install the CLI
        run: npm install -g fliplink-cli

      - name: Build the PDF
        run: ./scripts/build-report.sh   # your build that emits ./dist/report.pdf

      - name: Verify auth
        run: fliplink whoami

      - name: Create the flipbook
        run: |
          ID=$(fliplink flipbook create ./dist/report.pdf \
                 --title "Quarterly Report" --name quarterly \
                 --json | jq -r '.ID')
          echo "FLIPBOOK_ID=$ID" >> "$PIPELINE_ENV"

      - name: Publish the flipbook
        run: fliplink flipbook publish "$FLIPBOOK_ID"

      - name: Capture the share URL
        run: |
          URL=$(fliplink flipbook share-link "$FLIPBOOK_ID" \
                  --json | jq -r '.URL')
          echo "Published: $URL"

Il flusso si riduce a quattro comandi reali: costruisci il PDF, fliplink flipbook create, fliplink flipbook publish, poi fliplink flipbook share-link. Tutto il resto è l'impalcatura che la tua CI mette a disposizione.

Passo 3: cattura l'ID e l'URL del flipbook

Il trucco fondamentale è --json. Qualsiasi comando della FlipLink CLI lo accetta e stampa JSON grezzo, che passi a jq per estrarre esattamente il campo che ti serve:

# Create and grab the new flipbook's ID
ID=$(fliplink flipbook create ./dist/report.pdf \
       --title "Quarterly Report" --name quarterly \
       --json | jq -r '.ID')

# Publish it
fliplink flipbook publish "$ID"

# Grab the public share URL to post in Slack, an email, or a release note
URL=$(fliplink flipbook share-link "$ID" --json | jq -r '.URL')

Passa $ID da un passaggio all'altro nel modo in cui la tua CI condivide lo stato — una variabile di output, un file di environment o un artefatto scritto su disco. Per altri pattern con jq — filtrare liste, estrarre campi annidati, costruire tabelle — vedi scripting della CLI con jq.

🚀

Prova FlipLink Gratis

Converti il tuo PDF in pochi secondi. Senza registrazione, senza carta di credito — basta caricare il file.

Drop your PDF here or click to browse

Max 40MB

I piani a pagamento da $39 portano questo limite a 150 MB.

Passo 4: blocca subito tutto sugli exit code

Una pipeline vale quanto la sua gestione degli errori. La CLI ti dà tre exit code su cui ramificarti:

• 0 — successo
• 1 — errore di richiesta o HTTP (rete instabile, errore di autenticazione 401, upload troppo grande)
• 2 — errore applicativo (l'API ha restituito Result: ERROR, ad esempio un problema di validazione)

La maggior parte dei runner CI interrompe automaticamente un passaggio a qualsiasi uscita diversa da zero, ed è di solito quello che vuoi. Se hai bisogno di reagire in modo diverso a seconda del codice, ramifica esplicitamente:

set -euo pipefail

if fliplink flipbook publish "$ID" --json; then
  echo "Published OK"
else
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "FlipLink rejected the request (application error)" >&2
  else
    echo "Request/HTTP error talking to FlipLink" >&2
  fi
  exit "$code"
fi

Tieni presente che l'API di FlipLink restituisce gli errori di business come HTTP 200 con Result: ERROR nel corpo — la CLI li mappa già per te sull'exit code 2, quindi un controllo pulito dell'exit code è sufficiente. Non devi analizzare i codici di stato a mano.

Passo 5: notifica al successo

Una volta catturato l'URL, l'ultimo passaggio è semplicemente avvisare qualcuno. L'URL è una semplice stringa, quindi va bene qualsiasi sistema di notifica:

URL=$(fliplink flipbook share-link "$ID" --json | jq -r '.URL')

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{\"text\": \"New flipbook published: $URL\"}"

Sostituisci la chiamata curl con un'email, un commento su GitHub o una scrittura nel tuo changelog — il pattern è lo stesso. Poiché ogni passaggio si blocca subito in caso di errore, questa notifica parte solo quando la pubblicazione è andata davvero a buon fine.

Per concludere

Questo è l'intero pattern: salva la chiave come segreto, installa la CLI, costruisci il PDF, poi create → publish → cattura l'URL con --json | jq, con gli exit code a presidiare ogni passaggio. È abbastanza compatto da inserirsi in qualsiasi pipeline e abbastanza affidabile da dimenticartene — che è poi lo scopo dell'automazione e delle integrazioni.

Sei alle prime armi con la CLI? Inizia da primi passi con la FlipLink CLI, poi torna qui e collegala alla tua build.

Letture correlate

• Documentazione della FlipLink CLI
• Primi passi con la FlipLink CLI
• GitHub Actions: pubblica un flipbook al rilascio
• Scripting della FlipLink CLI con jq
• Automazione e integrazioni
• Riferimento API di FlipLink