GitHub Pages é a solução que mais recomendo quando alguém me pergunta como colocar um portfólio, uma documentação ou um site estático no ar sem gastar nada com hospedagem. Já usei para publicar dezenas de projetos pessoais e de clientes pequenos, e o processo continua simples — mas tem umas pegadinhas que só aparecem na prática, principalmente na hora de configurar domínio próprio. Vou passar o passo a passo completo, incluindo os erros mais comuns que vejo as pessoas cometerem.
Por que usar o GitHub Pages
Antes de mais nada: o GitHub Pages serve só para sites estáticos (HTML, CSS, JavaScript puro ou gerados por ferramentas como Jekyll, Hugo ou Next.js com export estático). Se o seu projeto precisa de banco de dados, PHP ou qualquer processamento no servidor, não vai funcionar aqui — para isso você precisaria de algo como Vercel, Netlify (que também têm planos gratuitos, mas com funções serverless) ou uma hospedagem tradicional.
Dito isso, para landing pages, portfólios, blogs estáticos e documentação de projetos, é difícil bater o custo-benefício: é gratuito, tem certificado HTTPS automático via Let’s Encrypt e se integra direto com o fluxo de trabalho que quem programa já usa no dia a dia.
Passo 1: organize os arquivos do projeto
Separe os arquivos do site numa pasta com uma estrutura simples:
meu-site/ ├── index.html ├── style.css └── script.js
Um detalhe que trava muita gente: o arquivo principal precisa se chamar index.html exatamente assim, em minúsculas. Servidores Linux (que é o que o GitHub usa) diferenciam maiúsculas de minúsculas — se você salvar como Index.html no Windows e funcionar localmente, no ar vai dar 404.
Passo 2: crie o repositório no GitHub
- Acesse sua conta no GitHub e clique em “New repository”.
- Dê um nome ao repositório (por exemplo,
meu-site) e marque como público — repositórios privados só publicam pelo GitHub Pages em planos pagos (Pro, Team ou Enterprise). - Clique em “Create repository”.
Se estiver subindo os arquivos pelo terminal, o fluxo é:
git init git add . git commit -m "Primeiro commit" git branch -M main git remote add origin https://github.com/seu-usuario/meu-site.git git push -u origin main
Se preferir, dá para fazer tudo isso pela própria interface web do GitHub, arrastando os arquivos direto no navegador — funciona bem para quem está começando e ainda não tem o Git instalado.
Passo 3: ative o GitHub Pages
Dentro do repositório, vá em Settings > Pages. Em “Build and deployment”, escolha a fonte:
- Deploy from a branch: mais simples, ideal para HTML/CSS/JS puro. Selecione a branch
maine a pasta/root(ou/docs, se você organizou os arquivos ali). - GitHub Actions: use se o site for gerado por Jekyll, Hugo, Next.js ou outro framework que precisa de um passo de build antes de publicar.
Depois de salvar, o GitHub leva de alguns segundos a poucos minutos para publicar. A URL segue o padrão https://seu-usuario.github.io/meu-site. Se o repositório se chamar exatamente seu-usuario.github.io, o site fica direto na raiz, sem o nome do projeto na URL.
Passo 4: configure um domínio próprio (se quiser)
Essa é a parte onde mais vejo gente travando. Depois de comprar o domínio (Registro.br, se for .com.br, ou Namecheap/GoDaddy para outras extensões):
- No provedor de DNS, crie os registros:
Registros A (para domínio raiz, ex: meusite.com): 185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153 Registro CNAME (para subdomínio, ex: www.meusite.com): seu-usuario.github.io
- Em Settings > Pages > Custom domain, digite o domínio e salve.
- O GitHub recomenda verificar a propriedade do domínio antes (em Settings do seu perfil > Pages > Add a domain), criando um registro TXT. Isso evita que outra pessoa “sequestre” seu domínio caso você remova o site depois.
O erro mais comum aqui: o GitHub cria um arquivo chamado CNAME na raiz do repositório quando você salva o domínio pela interface. Se você depois faz um novo commit sem esse arquivo (por exemplo, subindo os arquivos de novo do zero ou usando um script de build que sobrescreve tudo), o domínio custom simplesmente some e o site volta para a URL padrão do github.io. Sempre confira se o CNAME está sendo versionado junto com o resto do projeto.
A propagação de DNS pode levar de alguns minutos até 24 horas. Enquanto isso, a opção “Enforce HTTPS” fica desabilitada — é normal, o GitHub só libera depois que o certificado é emitido automaticamente.
Problemas comuns e como resolver
Site publicado mas aparece em branco ou com erro 404: confire se o arquivo se chama index.html (minúsculo) e está na raiz da pasta configurada. Erros de case-sensitivity são a causa mais frequente.
CSS ou imagens não carregam: geralmente é caminho relativo errado. Se o site está em usuario.github.io/meu-site, um link como /style.css vai procurar em usuario.github.io/style.css — o certo é usar ./style.css ou caminho relativo sem barra inicial.
HTTPS não ativa mesmo depois de dias: apague o domínio customizado no campo, salve, espere um minuto e digite de novo. Isso força o GitHub a tentar emitir o certificado novamente — resolve boa parte dos casos de certificado travado.
Perguntas frequentes
Dá para usar GitHub Pages para site comercial? Sim, desde que seja estático. Muita loja pequena usa para landing page e depois integra um checkout externo (Stripe, PagSeguro) via JavaScript.
Precisa pagar alguma coisa? Não, hospedagem e certificado SSL são gratuitos mesmo com domínio próprio. Você só paga pelo registro do domínio em si.
Posso usar Jekyll sem saber Ruby? Dá para ir bem longe só copiando temas prontos e editando os arquivos de configuração em YAML, sem escrever Ruby.
O GitHub Pages aguenta muito tráfego? Para blogs pessoais e portfólios, sim. Mas há um limite não oficial de banda (a documentação do GitHub menciona uso “razoável” e cerca de 100 GB/mês); para projetos com tráfego alto, vale migrar para Netlify, Vercel ou Cloudflare Pages.
Depois que o site estiver publicado, vale revisar as práticas de SEO que realmente funcionam em 2026 para o Google indexar corretamente, e se o projeto crescer, dá para migrar a arquitetura para JAMstack, que é essencialmente o modelo que o GitHub Pages já usa por baixo dos panos. Se o site vai consumir dados externos, o guia de como integrar APIs usando Node.js ajuda a entender onde processar isso, já que o Pages não roda backend.
