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

URL: https://skillaria.top/pt/guides/git/github-pages-publicar-site-gratis

O GitHub Pages é uma hospedagem gratuita de sites estáticos que funciona diretamente a partir de um repositório do GitHub. Você coloca o HTML, o CSS e o JavaScript no repositório, ativa o Pages nas configurações, e o site abre em um endereço do tipo usuario.github.io; também é possível conectar um domínio próprio e HTTPS, mas não há suporte a código de servidor como PHP nem a bancos de dados.

## 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.

| Tipo | Repositório | Endereço |
| --- | --- | --- |

| Site de usuário | `username.github.io` | `https://username.github.io/` |

| Site de organização | `orgname.github.io` | `https://orgname.github.io/` |

| Site de projeto | qualquer nome, por exemplo `docs` | `https://username.github.io/docs/` |

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 "

# Olá, GitHub Pages

" > 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.

| Limite | Valor |
| --- | --- |

| Conteúdo | apenas arquivos estáticos, sem código de servidor nem bancos de dados |

| Tamanho do site publicado | até 1 GB |

| Tamanho recomendado do repositório | até 1 GB |

| Tráfego | limite flexível de 100 GB por mês |

| Builds a partir de uma branch | limite flexível de 10 por hora (não se aplica ao Actions) |

| Tempo de publicação | deploy com mais de 10 minutos é interrompido |

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.

## FAQ

**O GitHub Pages é realmente gratuito?**

Sim, no plano gratuito do GitHub, para repositórios públicos, o Pages não custa nada, incluindo HTTPS e domínio próprio. Você paga apenas o domínio ao registrador e, se quiser publicar a partir de um repositório privado, um plano pago do GitHub.

**Dá para publicar no GitHub Pages um site em PHP ou WordPress?**

Não: o GitHub Pages entrega somente arquivos estáticos e não executa código de servidor. Um site WordPress pode ser exportado para HTML estático com plugins específicos, mas formulários, comentários e o painel administrativo não vão funcionar.

**Quantos sites posso criar no GitHub Pages?**

Um site de usuário no endereço username.github.io e uma quantidade ilimitada de sites de projeto, um para cada repositório.

**Os buscadores indexam sites do GitHub Pages?**

Sim, eles são indexados como qualquer outro site. Para melhorar a indexação, adicione os arquivos sitemap.xml e robots.txt na raiz e verifique o site nas ferramentas para webmasters dos buscadores.

**Como apago um site do GitHub Pages?**

Em Settings → Pages, clique em Unpublish site, se o botão estiver disponível, ou escolha None como fonte. Excluir o repositório também remove o site.


---
Source: Skillaria.Top (https://skillaria.top)