Usar fluxos de trabalho personalizados com o GitHub Pages

Você pode aproveitar o uso de GitHub Actions e GitHub Pages criando um arquivo de fluxo de trabalho ou escolhendo entre os fluxos de trabalho predefinidos.

Quem pode usar esse recurso?

O GitHub Pages está disponível em repositórios públicos com o GitHub Free e o GitHub Free para organizações, e em repositórios públicos e privados com o GitHub Pro, o GitHub Team, o GitHub Enterprise Cloud e o GitHub Enterprise Server. Para mais informações, confira "Planos do GitHub".

O GitHub Pages agora usa o GitHub Actions para executar a compilação Jekyll. Ao usar uma ramificação como a origem da sua compilação, o GitHub Actions deverá estar habilitado em seu repositório se você quiser usar o fluxo de trabalho interno do Jekyll. Como alternativa, se o GitHub Actions não estiver disponível ou estiver desabilitado, adicionar um .nojekyll arquivo à raiz da ramificação de origem ignorará o processo de compilação do Jekyll e implantará o conteúdo diretamente. Para mais informações sobre ativar o GitHub Actions, confira "Gerenciando as configurações do GitHub Actions para um repositório".

Neste artigo

Sobre fluxos de trabalho personalizados

Os fluxos de trabalho personalizados permitem que sites do GitHub Pages sejam criados por meio do uso de GitHub Actions. Você ainda pode selecionar o branch que deseja usar por meio do arquivo de fluxo de trabalho, mas pode fazer muito mais com o uso de fluxos de trabalho personalizados. Para começar a usar fluxos de trabalho personalizados, primeiro habilite-os para o repositório atual. Para obter mais informações, confira "Configurar uma fonte de publicação para o site do GitHub Pages".

Configurar a ação configure-pages

GitHub Actions permite o uso do GitHub Pages por meio da ação configure-pages, que também permite coletar metadados diferentes sobre um site. Para obter mais informações, confira a ação configure-pages.

Para usar a ação, coloque esse trecho em seu jobs no fluxo de trabalho desejado.

- name: Configure GitHub Pages
  uses: actions/configure-pages@v5

Essa ação ajuda a dar suporte à implantação de qualquer gerador de site estático para GitHub Pages. Para tornar esse processo menos repetitivo, você pode usar modelos de fluxo de trabalho para alguns dos geradores de site estático mais usados. Para obter mais informações, confira "Usando modelos de fluxo de trabalho".

Configurar a ação upload-pages-artifact

As ações de upload-pages-artifact permitem empacotar e carregar artefatos. O artefato GitHub Pages deve ser um arquivo compactado do gzip contendo um único arquivo tar. O arquivo tar deve ter menos de 10 GB de tamanho e não deve conter nenhum link simbólico ou físico. Para obter mais informações, confira a ação upload-pages-artifact.

Para usar a ação no fluxo de trabalho atual, coloque esse trecho em jobs.

- name: Upload GitHub Pages artifact
  uses: actions/upload-pages-artifact@v3

Implantar artefatos do GitHub Pages

A ação deploy-pages manipula a configuração necessária para implantar artefatos. Para garantir a funcionalidade adequada, os seguintes requisitos devem ser atendidos:

  • O trabalho precisa ter um mínimo de permissões pages: write e id-token: write.
  • O parâmetro needs deve ser definido como o id da etapa de build. Não definir esse parâmetro pode resultar em uma implantação independente que pesquisa continuamente um artefato que não foi criado.
  • É preciso estabelecer um environment para impor regras de proteção de branch/implantação. O ambiente padrão é github-pages.
  • Para especificar a URL da página como uma saída, utilize o campo url:.

Para obter mais informações, confira a ação deploy-pages.

# ...

jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: jekyll-build
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    steps:
      - name: Deploy artifact
        id: deployment
        uses: actions/deploy-pages@v4
# ...

Vincular trabalhos de build e implantação separados

Você pode vincular seus trabalhos build e deploy em um único arquivo de fluxo de trabalho, eliminando a necessidade de criar dois arquivos separados para obter o mesmo resultado. Para começar a usar o arquivo de fluxo de trabalho, em jobs você pode definir um trabalho build e deploy para executar seus trabalhos.

# ...

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
# ...

Em determinados casos, você pode optar por combinar tudo em um único trabalho, especialmente se não houver necessidade de um processo de build. Consequentemente, você se concentraria apenas na etapa de implantação.

# ...

jobs:
  # Single deploy job no building
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# ...

Você pode definir seus trabalhos para serem executados em diferentes executores, sequencialmente ou em paralelo. Para obter mais informações, confira "Escolhendo o que seu fluxo de trabalho faz".