GitHub Pages: hospedagem gratuita do seu site e como publicar passo a passo

O que é o GitHub Pages

O GitHub Pages é uma hospedagem gratuita de sites estáticos integrada ao GitHub. Você guarda os arquivos do site em um repositório Git comum, e o GitHub os entrega por HTTPS. Cada novo git push para a branch indicada atualiza o site, então não há necessidade de FTP, painel de hospedagem nem upload manual de arquivos.

Nas buscas em português o serviço aparece com nomes diferentes: «github pages», «github pages grátis», às vezes simplesmente «hospedagem github». Também se pesquisa «git pages o que é», mas o nome correto é GitHub Pages: trata-se de um recurso da plataforma GitHub, não do próprio Git. O Git não publica nada; ele apenas guarda o histórico das alterações.

O GitHub Pages costuma hospedar documentação de projetos, páginas pessoais e portfólios, blogs, landing pages e demos de front-end em React, Vue ou Svelte já compilados.

GitHub Pages é hospedagem de conteúdo estático

A palavra-chave é estático. O GitHub Pages entrega ao navegador arquivos já prontos: HTML, CSS, JavaScript, imagens, fontes, JSON. Ele não executa código no servidor: PHP, Python ou Node.js do lado do servidor e bancos de dados não funcionam aqui. Se o site precisa de cadastro de usuários, carrinho de compras ou um painel administrativo com banco de dados, será preciso uma hospedagem tradicional ou uma plataforma em nuvem.

O JavaScript continua funcionando no navegador normalmente. Uma aplicação de página única pode consultar APIs externas, formulários podem ser enviados por serviços de terceiros, e a busca no site pode ser feita no cliente.

Que tipos de sites existem no GitHub Pages

O GitHub Pages tem três tipos de site, e o tipo define o endereço.

Por conta, pode haver apenas um site de usuário ou de organização, mas sites de projeto podem ser quantos forem os repositórios, um por repositório. O nome do repositório do site pessoal precisa coincidir exatamente com o seu usuário no GitHub: se o seu usuário é ivan-petrov, o repositório se chama ivan-petrov.github.io.

Para repositórios públicos, o Pages está disponível no plano gratuito. Publicar um site a partir de um repositório privado exige um plano pago do GitHub; de qualquer forma, o site publicado fica visível para qualquer pessoa na internet.

Como publicar um site no GitHub Pages passo a passo

Vamos ao caminho mais simples: arquivos HTML prontos, publicados a partir de uma branch. Você precisa de uma conta no GitHub e do Git instalado.

Passo 1. Crie o repositório

No GitHub, crie um repositório público novo. Para um site pessoal, chame-o de username.github.io; para o site de um projeto, o nome é livre. Depois clone-o e adicione a página inicial:

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>Olá, GitHub Pages</h1>" > index.html

A página principal se chama obrigatoriamente index.html (ou index.md, ou README.md: o GitHub também os transforma na página inicial). As maiúsculas importam: Index.html não serve.

Passo 2. Envie os arquivos ao GitHub

git add index.html
git commit -m "Primeira página do site"
git push origin main

Se é a primeira vez que você envia alterações e o Git pede usuário e senha, use um token de acesso pessoal ou o login pelo navegador: a senha comum da conta do GitHub não funciona para git push por HTTPS.

Passo 3. Ative o Pages nas configurações

Abra o repositório no GitHub, entre em Settings e, no menu lateral, escolha Pages. No bloco Build and deployment, no campo Source, selecione Deploy from a branch. Logo abaixo, indique a branch (normalmente main) e a pasta: a raiz / (root) ou /docs. Clique em Save.

A pasta /docs é cômoda quando o repositório contém o código do projeto e, ao lado, um site com a documentação em um diretório separado.

Passo 4. Aguarde a publicação

A publicação leva de alguns segundos a alguns minutos; o GitHub avisa que a primeira pode demorar até 10 minutos. O andamento aparece na aba Actions: surgirá um processo chamado pages build and deployment. Quando ele terminar com um check verde, o endereço do site aparecerá em Settings → Pages.

A partir daí, é simples: você edita os arquivos, faz commit e git push, e o site se atualiza sozinho.

Publicação com GitHub Actions

A publicação a partir de uma branch serve quando o repositório contém arquivos já prontos. Se o site precisa ser compilado antes — por exemplo, uma aplicação com Vite, React ou um gerador como o Hugo —, a melhor opção é a fonte GitHub Actions. Em Settings → Pages, no campo Source, escolha GitHub Actions, e o GitHub oferece modelos de workflow prontos.

Um workflow mínimo para publicar os arquivos estáticos da pasta dist após a compilação tem esta aparência:

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

O arquivo é salvo em .github/workflows/pages.yml. Após o git push, o Actions instala as dependências, compila o projeto e publica o conteúdo de dist. A vantagem desse método é que o repositório guarda apenas o código-fonte, e os arquivos compilados não poluem o histórico de commits.

Uma armadilha frequente nos sites de projeto são os caminhos. O site abre em /nome-do-repositorio/, mas o compilador, por padrão, referencia os recursos a partir da raiz /. O resultado é uma página sem estilos e sem scripts. A solução é configurar o caminho base: no Vite, o parâmetro base: '/nome-do-repositorio/'; em outros compiladores, uma opção equivalente.

Jekyll e geradores de sites estáticos

Ao publicar a partir de uma branch, o GitHub processa os arquivos por padrão com o Jekyll, um gerador de sites estáticos escrito em Ruby. Por isso é possível escrever as páginas em Markdown, usar temas e modelos, e o GitHub as transforma em HTML. Para um blog ou uma documentação isso é cômodo: você escreve arquivos .md e o layout vem do tema.

Efeito colateral: o Jekyll ignora arquivos e pastas cujo nome começa com sublinhado, por exemplo _next ou _assets. Se o site foi compilado com outra ferramenta e essas pastas são necessárias, coloque na raiz um arquivo vazio .nojekyll:

touch .nojekyll
git add .nojekyll
git commit -m "Desativar Jekyll"
git push

Outros geradores — Hugo, Astro, Eleventy, MkDocs, Docusaurus — funcionam por meio do GitHub Actions: o workflow compila e publica a pasta resultante. O próprio GitHub Pages não conhece essas ferramentas; basta-lhe os arquivos finais.

Como conectar seu domínio ao GitHub Pages

O endereço username.github.io serve para projetos de estudo, mas para um portfólio ou um projeto é melhor um domínio próprio. A conexão é feita em dois lugares: no registrador do domínio e nas configurações do repositório.

Configuração de DNS

Para um subdomínio como www.example.com ou blog.example.com, crie um registro CNAME apontando para username.github.io. Para o domínio raiz example.com, crie registros A com os endereços IP do GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

A lista atual de endereços, inclusive IPv6 para os registros AAAA, está na documentação do GitHub; confira antes de configurar. Vale configurar tanto o domínio raiz quanto o www: assim o GitHub redireciona um endereço para o outro.

Configuração no repositório

Em Settings → Pages, digite o domínio no campo Custom domain e salve. Ao publicar a partir de uma branch, o GitHub cria no repositório um arquivo CNAME com o nome do domínio. Ao publicar pelo Actions, o arquivo CNAME não é necessário: o domínio fica guardado nas configurações.

O GitHub recomenda verificar o domínio nas configurações da conta (seção Pages dos ajustes do perfil). Isso protege contra alguém vincular o seu domínio ao próprio repositório enquanto o DNS aponta para o GitHub. As alterações de DNS levam até um dia para se propagar; se o domínio não funcionar de imediato, aguarde.

HTTPS no GitHub Pages

Para os endereços *.github.io, o HTTPS está sempre ativo. Para o seu próprio domínio, o GitHub emite sozinho um certificado Let's Encrypt quando o DNS está configurado corretamente. Depois disso, aparece em Settings → Pages a caixa Enforce HTTPS: marque-a para que todas as requisições por HTTP sejam redirecionadas para HTTPS.

Se a caixa estiver inativa, o certificado ainda não foi emitido: confira os registros de DNS e aguarde. Às vezes ajuda remover o domínio do campo Custom domain e adicioná-lo de novo, o que dispara uma nova emissão do certificado. Verifique também se o site não carrega imagens e scripts por http://: o navegador bloqueará esses recursos como conteúdo misto.

Limites do GitHub Pages

A hospedagem é gratuita, mas tem seus limites. Eles estão descritos na documentação do GitHub, e para a maioria dos sites pessoais e de estudo são mais do que suficientes.

Além dos limites técnicos, existem regras de uso: o GitHub Pages não é indicado para serviços comerciais como lojas virtuais ou SaaS, nem para distribuir arquivos grandes. Para portfólio, documentação, blog ou landing page de um projeto, é perfeitamente adequado.

Outra limitação é a falta de configuração de servidor. Não há redirecionamentos próprios, cabeçalhos de resposta nem regras no estilo .htaccess. Você pode apenas colocar uma página 404.html na raiz: o GitHub a mostrará para endereços inexistentes.

Problemas comuns e como resolvê-los

Erro 404 no GitHub Pages

A causa mais comum é não existir o arquivo index.html na pasta escolhida como fonte. Confira se você selecionou a branch e a pasta corretas (/ (root) ou /docs) e se o arquivo se chama exatamente index.html, em minúsculas. A segunda causa é o site ainda não ter sido publicado: veja a aba Actions e aguarde o fim da compilação.

Se o 404 aparece em páginas internas de uma aplicação de página única ao recarregar, o problema é de roteamento: o servidor não conhece o endereço /about, porque esse arquivo não existe. Alternativas são o roteamento por hash (/#/about) ou uma cópia de index.html com o nome 404.html.

O site não atualiza

Primeiro confirme que as alterações chegaram ao GitHub: execute git status e git log origin/main --oneline -3. Depois abra a aba Actions: se a compilação falhou, haverá um X vermelho e um log com o erro, por exemplo uma sintaxe errada em um arquivo do Jekyll ou uma falha no workflow.

Se a compilação terminou bem e o navegador mostra a versão antiga, a culpa é do cache. O GitHub Pages guarda os arquivos em cache por alguns minutos, e o navegador também guarda a sua própria cópia. Atualize a página limpando o cache (Ctrl+F5 ou Cmd+Shift+R) ou abra-a em uma janela anônima.

Estilos e imagens não carregam

Quase sempre são caminhos incorretos. Em um site de projeto, o link /style.css aponta para a raiz de username.github.io, não para a pasta do repositório. Use caminhos relativos (style.css, ./img/logo.png) ou defina o caminho base no compilador. Confira também as maiúsculas: os servidores do GitHub diferenciam Logo.PNG de logo.png, mesmo que no Windows, localmente, tudo funcionasse.

Sumiram as pastas que começam com sublinhado

É o Jekyll: ele não publica diretórios como _app. Adicione à raiz o arquivo .nojekyll ou passe a publicar pelo GitHub Actions.

Resumo

O GitHub Pages é a forma mais rápida de publicar gratuitamente um site estático: um repositório, um arquivo index.html e a fonte em Settings → Pages. Em alguns minutos o site está aberto em username.github.io. Para sites que precisam de compilação, use o GitHub Actions; para o seu próprio domínio, os registros de DNS e a caixa Enforce HTTPS. Lembre-se dos limites: apenas conteúdo estático, sem código de servidor e com restrições de tamanho e tráfego. O trabalho com o GitHub, o envio de alterações e a automação são explicados com prática no curso de Git.