GitHub Actions: genera in automatico un flipbook a ogni release

Se la documentazione, le note di rilascio o il catalogo prodotti vivono come PDF nel tuo repo, non c'è motivo di pubblicare il flipbook a mano. Con GitHub Actions e la CLI di FlipLink, ogni volta che tagli una release puoi creare il PDF, trasformarlo in un flipbook pubblicato e rimandare l'URL live direttamente sulla release — il tutto senza mai toccare la dashboard.

Questa è la versione GitHub-native della pubblicazione di flipbook in CI/CD. Se usi un runner diverso (GitLab CI, CircleCI, un cron box), i passaggi si adattano senza problemi — cambia solo la forma dello YAML.

Cosa stiamo costruendo

Un workflow che si attiva su una release pubblicata e:

1. Fa il checkout del repo e crea (o individua) il PDF che vuoi pubblicare.
2. Installa la CLI di FlipLink.
3. Crea e pubblica un flipbook a partire da quel PDF, autenticandosi con una chiave API salvata come secret del repo.
4. Recupera l'URL live del flipbook dall'output JSON.
5. Rimanda quell'URL sulla release, così il tuo team riceve il link all'istante.

È un esempio da manuale di automazione: un evento scatta, uno script gira, un artefatto viene rilasciato.

Passo 1 — Salva la chiave API come secret del repo

Non incollare mai una chiave API in un file di workflow. I file di workflow vivono nel tuo repo — chiunque abbia accesso in lettura (e ogni fork) può vederli. Usa invece un secret cifrato:

1. Accedi su https://go.fliplink.me, apri la pagina Subscription e copia la tua chiave API.
2. Nel tuo repo GitHub, vai su Settings → Secrets and variables → Actions.
3. Fai clic su New repository secret.
4. Chiamalo FLIPLINK_API_KEY e incolla la chiave come valore.
5. Fai clic su Add secret.

Il workflow la legge tramite secrets.FLIPLINK_API_KEY e la espone alla CLI come variabile d'ambiente FLIPLINK_API_KEY. La CLI controlla automaticamente quella variabile d'ambiente, quindi in CI non serve alcun passaggio config set-key.

Passo 2 — Il file di workflow

Crea .github/workflows/publish-flipbook.yml:

name: Publish flipbook on release

on:
  release:
    types: [published]

permissions:
  contents: write   # needed to edit the release notes in the last step

jobs:
  flipbook:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      # Replace this with however you produce the PDF.
      # If the PDF is committed in the repo, you can delete this step.
      - name: Build the PDF
        run: |
          mkdir -p dist
          # e.g. your doc tooling outputs dist/release-notes.pdf
          ls -lh dist/release-notes.pdf

      - name: Install FlipLink CLI
        run: npm install -g fliplink-cli

      - name: Create and publish flipbook
        id: flipbook
        env:
          FLIPLINK_API_KEY: ${{ secrets.FLIPLINK_API_KEY }}
        run: |
          ID=$(fliplink flipbook create ./dist/release-notes.pdf \
            --title "Release ${{ github.event.release.tag_name }}" \
            --name "release-${{ github.event.release.tag_name }}" \
            --json | jq -r '.ID')

          fliplink flipbook publish "$ID"

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

          echo "id=$ID" >> "$GITHUB_OUTPUT"
          echo "url=$URL" >> "$GITHUB_OUTPUT"
          echo "Published flipbook: $URL"

      - name: Comment the URL on the release
        uses: actions/github-script@v7
        with:
          script: |
            const url = "${{ steps.flipbook.outputs.url }}";
            const release = context.payload.release;
            await github.rest.repos.updateRelease({
              owner: context.repo.owner,
              repo: context.repo.repo,
              release_id: release.id,
              body: `${release.body || ""}\n\nFlipbook published: ${url}`
            });

Qualche nota sul passo di creazione:

• fliplink flipbook create ./path.pdf carica il PDF e restituisce il nuovo flipbook. Con --json ottieni la risposta grezza, e jq -r '.ID' ne estrae l'ID.
• fliplink flipbook publish "$ID" lo mette online. (La creazione di un flipbook non lo pubblica — la pubblicazione è un passaggio separato ed esplicito.)
• fliplink flipbook share-link "$ID" restituisce l'URL pubblico del visualizzatore, che recuperiamo allo stesso modo con jq.
• Scriviamo id e url su $GITHUB_OUTPUT, così i passaggi successivi possono richiamarli come steps.flipbook.outputs.url.

Qui dentro si usano solo comandi documentati della CLI e il flag --json. Se ti serve un'azione che la CLI non include, ricorri alla scorciatoia fliplink api — consulta la documentazione della CLI per l'intera superficie, oppure il riferimento API per ogni endpoint.

🚀

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 3 — Rimandare indietro l'URL

Il modo più pulito per far emergere l'URL è commentarlo sulla release stessa. Il passo actions/github-script qui sopra fa proprio questo. Se preferisci la CLI di GitHub (gh è preinstallata sui runner ospitati da GitHub), funziona anche questa riga:

      - name: Comment via gh
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh release view "${{ github.event.release.tag_name }}" \
            --json body --jq '.body' > old-body.txt
          printf '\n\nFlipbook: %s\n' "${{ steps.flipbook.outputs.url }}" >> old-body.txt
          gh release edit "${{ github.event.release.tag_name }}" \
            --notes-file old-body.txt

In questo modo il link del flipbook viene aggiunto alle note di rilascio, così resta visibile proprio dove le persone leggono il changelog. Scegli ciò che si adatta meglio alle abitudini del tuo team — entrambe leggono l'URL dallo stesso steps.flipbook.outputs.url.

Note su caching e performance

Alcuni accorgimenti che mantengono questo workflow veloce e prevedibile:

• Metti in cache npm. Aggiungi cache: npm al passo setup-node se il tuo repo ha un lockfile — velocizza l'installazione della CLI e di qualsiasi strumento per il PDF nelle esecuzioni successive.
• Tieni d'occhio il rate limit. L'API di FlipLink consente 300 richieste al minuto per chiave. Una singola release pubblica un flipbook, quindi sei ben lontano dal tetto — ma se distribuisci molti PDF in un solo job, distanzia le chiamate.
• Ramifica in caso di errore. La CLI esce con 0 in caso di successo, 1 in caso di errore di richiesta/HTTP e 2 in caso di errore applicativo. Poiché ogni comando nel blocco run può fallire, il passo fallisce in modo evidente se qualcosa va storto — che è esattamente ciò che vuoi in CI.
• Mantieni il trigger ristretto. types: [published] significa che il workflow gira una sola volta, quando pubblichi davvero una release — non sulle bozze né sulle modifiche pre-pubblicazione. Così eviti flipbook duplicati per errore.

Per concludere

Con un solo file di workflow e un solo secret del repo, ogni release ora rilascia un flipbook pubblicato e rimanda il link al tuo team — zero passaggi manuali. Da qui puoi convertire in blocco un'intera cartella, scrivere pipeline più ricche con jq oppure spostare la logica in un agente AI. Tutti questi schemi si basano sulla stessa CLI.

Letture correlate

• Primi passi con la CLI di FlipLink
• Automatizza la pubblicazione dei flipbook nella tua pipeline CI/CD
• Documentazione della CLI
• Riferimento API di FlipLink
• Che cos'è l'automazione? (glossario)