GitHub Actions: gere um flipbook automaticamente a cada release

Se a sua documentação, suas notas de release ou seu catálogo de produtos ficam como um PDF no seu repositório, não há motivo para publicar o flipbook na mão. Com o GitHub Actions e a CLI do FlipLink, toda vez que você lança uma release dá para criar o PDF, transformá-lo em um flipbook publicado e postar a URL ao vivo direto na release — tudo sem encostar no painel.

Esta é a versão nativa do GitHub para publicação de flipbook com CI/CD. Se você usa outro runner (GitLab CI, CircleCI, uma máquina com cron), os passos se traduzem facilmente — só muda o formato do YAML.

O que vamos construir

Um workflow que dispara em uma release publicada e:

1. Faz o checkout do repositório e cria (ou localiza) o PDF que você quer publicar.
2. Instala a CLI do FlipLink.
3. Cria e publica um flipbook a partir desse PDF, autenticando com uma chave de API guardada como secret do repositório.
4. Captura a URL ao vivo do flipbook a partir da saída em JSON.
5. Comenta essa URL de volta na release para que sua equipe receba o link na hora.

É um exemplo clássico de automação: um evento dispara, um script roda, um artefato é entregue.

Passo 1 — Guarde sua chave de API como secret do repositório

Nunca cole uma chave de API em um arquivo de workflow. Os arquivos de workflow ficam no seu repositório — qualquer pessoa com acesso de leitura (e todo fork) pode vê-los. Use um secret criptografado em vez disso:

1. Faça login em https://go.fliplink.me, abra a página Subscription e copie sua chave de API.
2. No seu repositório do GitHub, vá em Settings → Secrets and variables → Actions.
3. Clique em New repository secret.
4. Dê o nome FLIPLINK_API_KEY e cole a chave como valor.
5. Clique em Add secret.

O workflow lê a chave via secrets.FLIPLINK_API_KEY e a expõe à CLI como a variável de ambiente FLIPLINK_API_KEY. A CLI verifica essa variável de ambiente automaticamente, então não é preciso nenhum passo de config set-key no CI.

Passo 2 — O arquivo de workflow

Crie o .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}`
            });

Algumas observações sobre o passo de criação:

• fliplink flipbook create ./path.pdf faz o upload do PDF e retorna o novo flipbook. Com --json você recebe a resposta bruta, e jq -r '.ID' extrai o ID.
• fliplink flipbook publish "$ID" coloca o flipbook no ar. (Criar um flipbook não o publica — publicar é um passo separado e explícito.)
• fliplink flipbook share-link "$ID" retorna a URL pública do visualizador, que capturamos da mesma forma com jq.
• Gravamos id e url em $GITHUB_OUTPUT para que os passos seguintes possam referenciá-los como steps.flipbook.outputs.url.

Tudo aqui usa apenas comandos documentados da CLI e a flag --json. Se você precisar de uma ação que a CLI não cobre, recorra ao escape hatch fliplink api — veja a documentação da CLI para a superfície completa, ou a referência da API para cada endpoint.

Experimente o FlipLink Grátis

Converta seu PDF em segundos. Sem cadastro, sem cartão de crédito — basta enviar o arquivo.

Drop your PDF here or click to browse

Máx 40MB

Os planos pagos a partir de $39 aumentam esse limite para 150 MB.

Passo 3 — Comentando a URL de volta

A forma mais limpa de mostrar a URL é comentá-la na própria release. O passo actions/github-script acima faz isso. Se você preferir a CLI do GitHub (gh já vem instalado nos runners hospedados pelo GitHub), esta linha única também funciona:

      - 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

Isso anexa o link do flipbook às notas de release, deixando-o visível bem onde as pessoas leem o changelog. Escolha o que combina mais com os hábitos da sua equipe — os dois leem a URL do mesmo steps.flipbook.outputs.url.

Notas sobre cache e desempenho

Algumas coisas que mantêm este workflow rápido e previsível:

• Faça cache do npm. Adicione cache: npm ao passo setup-node se o seu repositório tiver um lockfile — isso acelera a instalação da CLI e de qualquer ferramenta de PDF em execuções repetidas.
• Fique de olho no rate limit. A API do FlipLink permite 300 requisições por minuto por chave. Uma única release publica um flipbook, então você está bem longe do teto — mas se você espalhar muitos PDFs em um job só, espace as chamadas.
• Trate as falhas. A CLI sai com 0 em caso de sucesso, 1 em erro de requisição/HTTP e 2 em erro de aplicação. Como cada comando do bloco run pode falhar, o passo falha de forma clara se algo der errado — que é exatamente o que você quer no CI.
• Mantenha o gatilho enxuto. types: [published] significa que o workflow roda uma vez, quando você de fato publica uma release — não em rascunhos nem em edições antes da publicação. Isso evita flipbooks duplicados por acidente.

Para finalizar

Com um arquivo de workflow e um secret de repositório, toda release agora entrega um flipbook publicado e posta o link de volta para sua equipe — zero passos manuais. A partir daqui você pode converter em lote uma pasta inteira, montar pipelines mais ricos com jq ou mover a lógica para um agente de IA. Todos os padrões se apoiam na mesma CLI.

Leitura relacionada

• Primeiros passos com a CLI do FlipLink
• Automatize a publicação de flipbooks no seu pipeline de CI/CD
• Documentação da CLI
• Referência da API do FlipLink
• O que é automação? (glossário)