Hospedagem gratuita com GitHub
O GitHub Pages é o serviço do GitHub que permite publicar sites estáticos gratuitamente, direto a partir de um repositório. Com ele, você coloca no ar um portfólio, uma página de projeto ou uma documentação sem pagar nada por hospedagem.
Apesar de ter limites de uso, a ferramenta atende muito bem a diversos cenários. Neste artigo, você vai entender como ela funciona e publicar o seu primeiro site passo a passo.
O que é o GitHub Pages
Segundo a documentação oficial, o GitHub Pages é um serviço de hospedagem de sites estáticos. Ele pega arquivos HTML, CSS e JavaScript de um repositório, opcionalmente executa um processo de build e publica o resultado como um site.
No plano gratuito, a publicação funciona a partir de repositórios públicos. Também é possível publicar a partir de repositórios privados, porém apenas nos planos pagos, como GitHub Pro, GitHub Team e GitHub Enterprise.
Neste artigo, o foco fica no uso gratuito, com um repositório público de uma organização. Assim, você consegue reproduzir todo o processo sem nenhum custo.
Tipos de site no GitHub Pages
Existem dois tipos de site. O primeiro é o site de usuário ou de organização, que usa um repositório chamado <owner>.github.io e fica disponível em https://<owner>.github.io.
Cada conta pode ter apenas um site desse tipo. Já o segundo tipo, o site de projeto, pode existir em qualquer repositório e fica em https://<owner>.github.io/<repository-name>.
Neste tutorial, vamos publicar um site de projeto. Por isso, o endereço final terá o nome da organização seguido do nome do repositório.
O que são sites estáticos
Sites estáticos são aqueles formados por HTML (HyperText Markup Language), CSS (Cascading Style Sheets) e JS (JavaScript), sem um sistema de gerenciamento de conteúdo por trás. Ou seja, não existe banco de dados nem código rodando no servidor a cada requisição.
Isso significa que, para atualizar ou modificar o site, você altera diretamente o código-fonte. Em seguida, basta publicar a nova versão dos arquivos.
Com o GitHub Pages, você pode criar um site estático para diversos fins. Por exemplo, um portfólio profissional, uma página de contato, a apresentação de um projeto ou a documentação de uma biblioteca.
Também é possível usar geradores de sites estáticos, como o Jekyll, que transformam arquivos Markdown em páginas HTML. No entanto, para começar, um simples arquivo index.html já resolve.
Limites do GitHub Pages
Antes de publicar, vale conhecer os limites da hospedagem gratuita. Afinal, eles definem o tipo de projeto que cabe no serviço.
- O repositório de origem tem um limite recomendado de 1 GB.
- O site publicado não pode passar de 1 GB.
- Existe um limite flexível de 100 GB de banda por mês.
- Existe um limite flexível de 10 builds por hora, que não vale quando você publica com um workflow próprio do GitHub Actions.
- Cada deploy expira se levar mais de 10 minutos.
Na prática, esses números atendem com folga a portfólios, blogs pessoais e documentações. Quando o tráfego passa dos limites flexíveis, o GitHub pode entrar em contato e, em alguns casos, aplicar limitação de requisições.
Usos proibidos
O serviço não foi pensado para tudo. A documentação deixa claro que ele não deve ser usado como hospedagem gratuita para negócios online, sites de comércio eletrônico ou software como serviço.
Além disso, o GitHub proíbe sites que transmitam informações sensíveis, como senhas ou números de cartão de crédito. Portanto, para aplicações com backend e dados de usuários, procure outro tipo de hospedagem.
Pré-requisitos para usar o GitHub Pages
Para seguir o passo a passo, você precisa de uma conta no GitHub e do Git instalado na sua máquina. Se ainda não tem o ambiente pronto, o artigo Git e GitHub: instalação, configuração e primeiros passos mostra cada etapa.
Também vamos usar o repositório de uma organização criada em artigos anteriores. Caso queira montar uma do zero, veja o guia de gestão de organizações com GitHub.
Como publicar o site no GitHub Pages
Para publicar o site, primeiro acesse o repositório onde ele está armazenado. A partir daí, a configuração leva poucos cliques.
Passo 1: acesse as configurações do repositório
No menu superior do repositório, clique em Settings. É nessa área que ficam todas as opções de publicação.
Passo 2: abra a seção Pages
No menu lateral, encontre a seção Code and automation (Código e automação). Em seguida, selecione o item Pages (Páginas).
Passo 3: escolha a branch de publicação
Na seção Build and deployment, em Source, escolha Deploy from a branch. Depois, selecione a branch onde o código do site está armazenado e a pasta de origem, que pode ser a raiz (/) ou a pasta /docs.
Na interface mostrada abaixo, também aparece a opção de escolher um tema oferecido pelo próprio GitHub. Por fim, clique em Save para salvar.
A partir de agora, o serviço lê o conteúdo da branch selecionada. O site fica acessível pelo link exibido após salvar, que segue este formato:
https://organization-name.github.io/repository-name/
Passo 4: crie o arquivo index.html
Agora precisamos de um arquivo de entrada na raiz da branch escolhida. O GitHub Pages procura um index.html, um index.md ou um README.md, e a navegação do site parte dele.
Você pode adicionar pastas e acessá-las normalmente por meio das referências dentro do código. Como exemplo, vamos publicar uma página com um template estático de blog da W3Schools.
Um index.html mínimo já basta para testar a publicação:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>My first site</title>
</head>
<body>
<!-- conteúdo da página -->
<h1>Hello, GitHub Pages!</h1>
</body>
</html>
Passo 5: envie os arquivos para o repositório
Para clonar o repositório na sua máquina, use o comando abaixo no terminal:
git clone https://github.com/organization-name/repository-name.git
Depois de adicionar os arquivos desejados dentro do repositório, registre as mudanças com os comandos:
git add --all
git commit -m "Add static site"
Então, envie as modificações para o GitHub:
git push -u origin main
Se algum desses comandos for novidade para você, o artigo de primeiros passos com Git e GitHub, citado nos pré-requisitos, explica cada um em detalhe.
Passo 6: acompanhe o deploy no GitHub Actions
Assim que você envia o index.html para a branch configurada, o GitHub inicia automaticamente o processo de deploy, ou seja, a publicação do site. Para acompanhar, clique em Actions no menu superior do repositório.
Mesmo quando você publica a partir de uma branch, o deploy roda como um workflow do GitHub Actions. Por isso, é ali que aparecem os detalhes de cada publicação e os eventuais erros.
Passo 7: confira o resultado
Quando o processo terminar, abra o link informado na configuração do serviço. O site estático estará no ar, pronto para receber visitas.
Publicação no GitHub Pages com GitHub Actions
Além da publicação a partir de uma branch, existe uma segunda fonte de publicação. Em Source, você pode escolher GitHub Actions e usar um workflow próprio para gerar e publicar o site.
Essa opção é útil quando o projeto precisa de um build, como em sites feitos com React, Vue, Astro ou outros frameworks. Nesse caso, o GitHub sugere modelos de workflow prontos para os cenários mais comuns.
Outra vantagem é que o limite flexível de 10 builds por hora não vale para workflows próprios. Se quiser aprofundar a automação, o artigo sobre workflows reutilizáveis no GitHub Actions é um bom próximo passo.
Dicas para usar o GitHub Pages no dia a dia
Algumas configurações extras ajudam a deixar o site mais profissional e evitam problemas comuns.
Domínio personalizado no GitHub Pages
Você pode trocar o endereço github.io por um domínio próprio. A configuração fica na mesma tela de Pages, no campo de domínio personalizado.
Além disso, o próprio serviço disponibiliza HTTPS para os sites. Assim, os visitantes acessam o conteúdo por uma conexão segura.
Arquivo .nojekyll
Ao publicar a partir de uma branch, o serviço processa os arquivos com o Jekyll por padrão. Se o site já está pronto e não precisa de build, crie um arquivo vazio chamado .nojekyll na raiz da fonte de publicação.
Esse arquivo também evita que pastas iniciadas com sublinhado, como _assets, sejam ignoradas na publicação.
Documentação de projetos
Um uso muito comum é publicar a documentação de um projeto a partir da pasta /docs. Dessa forma, o código e a documentação vivem no mesmo repositório.
Para entender melhor esse cenário, veja o artigo Documentação com GitHub.
Quando usar o GitHub Pages
O GitHub Pages brilha em projetos em que o conteúdo muda pouco e não depende de processamento no servidor. Portfólios, currículos online, landing pages de projetos open source e documentações técnicas são os exemplos mais clássicos.
Também é uma ótima escolha para estudar desenvolvimento web. Afinal, você pratica HTML, CSS e JavaScript e mostra o resultado para qualquer pessoa com apenas um link.
Por outro lado, ele não é a ferramenta certa quando o projeto precisa de login, banco de dados ou regras de negócio no servidor. Nesses casos, o site estático pode até consumir uma API hospedada em outro serviço, mas a lógica sensível fica fora dele.
Problemas comuns no GitHub Pages
Mesmo com um processo simples, alguns erros aparecem com frequência na primeira publicação. Conhecer cada um deles economiza bastante tempo.
Erro 404 ao abrir o site
O erro mais comum é abrir o endereço e receber uma página 404. Em geral, isso acontece porque não existe um arquivo de entrada na raiz da fonte de publicação.
Portanto, confira se o index.html está na pasta escolhida, seja a raiz ou a pasta /docs. Confira também se a branch configurada é a mesma em que você fez o push.
Caminhos quebrados em sites de projeto
Em um site de projeto, o endereço inclui o nome do repositório depois do domínio. Por isso, referências absolutas como /css/style.css apontam para a raiz do domínio, e não para a pasta do projeto.
Nesse caso, prefira caminhos relativos, como css/style.css. Além disso, lembre que o servidor diferencia maiúsculas de minúsculas nos nomes de arquivos.
Alterações que demoram a aparecer
Se o deploy terminou e a mudança não aparece, o problema costuma ser cache do navegador. Então, recarregue a página forçando a atualização ou abra o site em uma janela anônima.
Se mesmo assim nada mudar, volte à aba Actions e verifique se o último workflow terminou com sucesso.
Agora é com você
Use o GitHub Pages para publicar os seus sites. Assim, as pessoas podem experimentar algo feito por você, e outros desenvolvedores podem se inspirar no resultado do seu trabalho.
Crie seu portfólio e adicione o link ao currículo. Ou, então, crie o seu currículo online e compartilhe o endereço, porque as possibilidades são muitas.
Para consultar detalhes, a documentação oficial do GitHub Pages traz guias para cada cenário.
Continue lendo
- Git e GitHub: instalação, configuração e primeiros passos
- Gestão de projetos com GitHub
- Gestão de equipes com GitHub
Cursos relacionados
Gratuito | Fundamentos do Git e Azure DevOps
Conclusão
O GitHub Pages é uma das formas mais simples de colocar um site estático no ar sem custo. Com um repositório público, um index.html e poucos cliques nas configurações, o site fica disponível em minutos.
Além disso, o serviço integra a publicação ao fluxo que você já usa com Git. Ou seja, cada push na branch configurada gera um novo deploy automaticamente.
Por outro lado, os limites de tamanho e de banda e as regras de uso mostram que ele não substitui uma hospedagem para aplicações comerciais. Ainda assim, para portfólios, documentações e projetos pessoais, o GitHub Pages é difícil de superar.
Agora que você conhece o passo a passo, os limites e os problemas mais comuns, publique o seu primeiro site. Em seguida, evolua para um workflow próprio no GitHub Actions quando o projeto pedir um processo de build.
FAQ
O GitHub Pages é realmente gratuito?
Sim, para repositórios públicos ele não tem custo. Para publicar a partir de repositórios privados, você precisa de um plano pago, como o GitHub Pro.
Posso hospedar uma aplicação com backend?
Não. O serviço hospeda apenas arquivos estáticos, então APIs e bancos de dados precisam ficar em outro lugar.
Quanto tempo leva para o site ficar no ar?
Em geral, poucos minutos após o push. Você acompanha o andamento na aba Actions do repositório.
Posso usar um domínio próprio?
Sim. Basta configurar o domínio personalizado na tela de Pages e ajustar os registros DNS no seu provedor.
Qual arquivo o site abre primeiro?
O serviço procura um index.html, um index.md ou um README.md na raiz da fonte de publicação.