Desmistificando o Workflow do GitHub Actions para este Blog Hugo

junho 2, 2025 · 4 minutos · Rennan

Esta não é a primeira tentativa de criar um lugar para armazenar publicamente minhas ideias. Provavelmente não será a última também. Tudo que eu queria era usar um domínio meu, e evitar pagar recorrentemente por armazenamento e processamento para algo que não vai ser visto exceto por menos de uma dúzia de pessoas.

Tentei muitas soluções no passado para sites estáticos dentro do GitHub Pages, como Jekyll e Django. Também tentei soluções gratuitas que depois de um tempo ficaram bem populares, mas o principal problema era continuar publicando coisas. Acho que depois de cerca de 10 anos de arrependimento por não ter mantido, aqui estamos numa tentativa (esperançosamente) bem-sucedida.

Parece que Hugo é o que a galera está curtindo ultimamente. Após um pouco de jornada, cheguei a um workflow estável do GitHub Actions para automaticamente construir e fazer deploy deste blog estático com o tema PaperMod. Este post quebra os componentes principais e versões usadas, para que você possa replicar este experimento ou entender o que o faz funcionar.

Visão Geral da Estrutura do Workflow

Este workflow, definido em .github/workflows/hugo.yml, usa um único job chamado deploy. Este job cuida de tudo, desde fazer checkout do código até fazer deploy do site construído final.

Aqui está uma visão de alto nível dos passos envolvidos no job deploy:

  1. Checkout do Código: Busca a versão mais recente do seu repositório, incluindo submódulos (para o tema, PaperMod neste caso).
  2. Setup do Hugo: Baixa e instala a versão específica do Hugo requerida pelo tema PaperMod.
  3. Construir Site: Executa o comando hugo para gerar os arquivos do site estático. Também copia o arquivo CNAME para um domínio customizado no diretório de saída.
  4. Setup do Pages: Configura o ambiente para deployment do GitHub Pages.
  5. Upload do Artifact: Empacota o site construído (resultante no diretório public) em um artifact que o GitHub Pages pode usar.
  6. Deploy para GitHub Pages: Pega o artifact enviado e faz o deploy.

Actions do GitHub e Versões Principais

Acertar as versões das GitHub Actions foi crucial. Aqui está o que funcionou:

  • actions/checkout@v4:

    • Propósito: Faz checkout do seu repositório sob $GITHUB_WORKSPACE, para que o workflow possa acessá-lo.
    • Configuração: Usado com submodules: true para garantir que o tema PaperMod (que é um submódulo) também seja buscado, e fetch-depth: 0 para obter o histórico completo do git (útil para algumas funcionalidades do Hugo que provavelmente vou estudar mais tarde).

  • Instalação Manual do Hugo (v0.146.0):

    • Propósito: Ao invés de uma action dedicada “setup Hugo”, baixamos e instalamos diretamente uma versão específica do Hugo. Isso foi feito porque o tema PaperMod requer Hugo v0.146.0 ou mais recente. Este foi um aspecto chave que ignorei no início,
    • Método:
      HUGO_VERSION=0.146.0
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb

  • actions/configure-pages@v4:

    • Propósito: Esta action configura o ambiente do GitHub Pages, preparando-o para o deployment. Ajuda a configurar variáveis de ambiente e configurações necessárias.

  • actions/upload-pages-artifact@v3:

    • Propósito: Pega a saída da sua construção Hugo (tipicamente o diretório public/) e envia como um artifact especificamente projetado para GitHub Pages.
    • Nota: Chegamos na v3 como a versão estável mais recente que resolveu erros anteriores de “Missing download info” que ocorreram devido ao GitHub depreciar versões mais antigas das actions de artifact.

  • actions/deploy-pages@v4:

    • Propósito: Este é o passo final que realmente faz deploy do artifact enviado para o GitHub Pages, deixando seu site no ar.

Permissões

O workflow também especifica permissões necessárias:

permissions:
  contents: read
  pages: write
  id-token: write

Estas são importantes para permitir que as actions leiam o conteúdo do seu repositório, escrevam no GitHub Pages, e usem um token ID para autenticação.

Conclusão

Esta configuração garante que todo push para o branch main (ou um dispatch manual) dispare uma construção e deployment fresh do site Hugo. Usando versões específicas para as actions e Hugo propriamente dito, mantemos estabilidade e evitamos problemas causados por atualizações inesperadas ou depreciações.

Espero que esta análise detalhada ajude se você estiver configurando um deployment Hugo similar!

Go to top