GitHub: o Que É, Para Que Serve e Como Usar de Verdade

Muita gente aprende Git e GitHub como se fossem a mesma coisa. Não são — e entender a diferença é o primeiro passo para usar os dois bem.

• Git é o sistema de controle de versão. Roda na sua máquina, funciona offline e é quem de fato guarda o histórico do código.
• GitHub é uma plataforma na internet construída em volta do Git. Hospeda repositórios e acrescenta o que o Git não tem: colaboração, revisão de código, automação, publicação e uma rede social de desenvolvedores.

Dá para usar Git a vida toda sem GitHub. O que você perde é tudo que acontece entre pessoas.

Índice

• 1 · Por que o GitHub existe
• 2 · Repositório: a unidade de tudo
• 3 · O fluxo de trabalho na prática
• 4 · Pull Request: onde o código é revisado
• 5 · Issues e organização do trabalho
• 6 · GitHub Actions: automação e CI/CD
• 7 · Releases, Pages e Packages
• 8 · Segurança
• 9 · GitHub como portfólio
• 10 · Alternativas e quando escolher outra

1. Por que o GitHub existe

Git resolve o versionamento, mas deixa três perguntas em aberto:

1. Onde fica a cópia oficial? Se o código só existe na sua máquina, um HD queimado encerra o projeto.
2. Como eu proponho uma mudança para outra pessoa? Git tem format-patch e e-mail — funciona, mas é do tempo em que o Linux era desenvolvido por lista de discussão.
3. Como garanto que ninguém quebre a build? Git não roda teste, não bloqueia merge, não avisa ninguém.

O GitHub responde às três: repositório remoto como fonte da verdade, pull request como forma padronizada de propor mudança e Actions para automatizar verificação e deploy.

2. Repositório: a unidade de tudo

Um repositório ("repo") é o projeto: código, histórico, documentação e configuração.

• Público — qualquer pessoa vê e clona. É o que sustenta o open source.
• Privado — só quem você autoriza. Gratuito e ilimitado desde 2019, inclusive em conta pessoal.

Três arquivos definem a primeira impressão do seu repositório:

README.md          # o que é, como rodar, como contribuir — vira a capa do repositório
.gitignore         # o que nunca deve ser versionado (node_modules, .env, build)
LICENSE            # sem licença, "público" não significa "livre para usar"

Repositório público sem licença é, juridicamente, "todos os direitos reservados". Se você quer que usem seu código, escolha uma licença — MIT e Apache 2.0 são as mais comuns.

E o aviso que vale por todos: nunca commite segredo. Token, senha e chave privada em repositório público são varridos por bots em minutos. Se aconteceu, revogue a credencial antes de qualquer outra coisa — apagar o commit não basta, porque ela já foi lida.

3. O fluxo de trabalho na prática

O ciclo que praticamente toda equipe usa:

# 1. Traga o estado atual da branch principal
git switch main
git pull

# 2. Crie uma branch para a sua tarefa
git switch -c feat/filtro-por-assunto

# 3. Trabalhe em commits pequenos e descritivos
git add .
git commit -m "feat(blog): filtro por assunto na listagem"

# 4. Publique a branch
git push -u origin feat/filtro-por-assunto

# 5. Abra o Pull Request (pelo site ou pelo gh CLI)
gh pr create --fill

Por que branch em vez de commitar direto na main? Porque a main deveria estar sempre publicável. Toda mudança passa por um lugar onde pode ser revisada, testada e desfeita sem afetar quem depende dela.

O gh CLI

O GitHub tem um cliente de linha de comando que evita ficar indo ao navegador:

gh auth login                          # autentica a máquina
gh repo create meu-projeto --private   # cria o repositório
gh repo clone usuario/projeto
gh pr create --fill                    # abre PR com título/corpo dos commits
gh pr list
gh pr checkout 42                      # baixa o PR de outra pessoa para testar
gh pr review 42 --approve
gh pr merge 42 --squash --delete-branch
gh issue create --title "Bug no filtro" --body "Passos para reproduzir..."
gh run list                            # execuções do Actions
gh run watch                           # acompanha a execução atual

4. Pull Request: onde o código é revisado

O Pull Request (PR) é o coração do GitHub. Ele diz: "tenho estas mudanças nesta branch e quero integrá-las naquela; revisem".

Um PR reúne em um só lugar:

• o diff completo, comentável linha a linha;
• a discussão sobre as decisões;
• o resultado da automação (testes, lint, build, preview de deploy);
• as aprovações exigidas antes do merge.

O que faz um bom PR:

Três formas de mesclar, e quando usar cada uma:

• Merge commit — preserva todos os commits e registra a integração. Bom quando o histórico da branch tem valor.
• Squash and merge — junta tudo em um commit só na main. O padrão da maioria das equipes: histórico limpo, um commit por funcionalidade.
• Rebase and merge — reaplica os commits sem commit de merge. História linear, mas reescreve os hashes.

Proteção de branch

Nas configurações do repositório você define as regras da main:

• exigir PR (bloquear push direto);
• exigir N aprovações;
• exigir que os checks de CI passem;
• exigir a branch atualizada antes do merge;
• exigir commits assinados.

É o que transforma boa intenção em processo. Sem isso, o "combinamos de sempre abrir PR" dura até a primeira sexta-feira apertada.

5. Issues e organização do trabalho

Issues são as tarefas, bugs e ideias do projeto — cada uma com discussão, responsável, rótulos e marco.

# No corpo do commit ou do PR, isto fecha a issue automaticamente ao mesclar:
git commit -m "fix: corrige contraste do tema claro

Closes #42"

Recursos que valem conhecer:

• Labels — bug, enhancement, good first issue. O último é o convite clássico para novos contribuidores.
• Milestones — agrupam issues por entrega ou versão.
• Projects — quadro estilo kanban ligado às issues e PRs, que se movem sozinhos conforme o status muda.
• Discussions — para dúvidas e propostas abertas, sem poluir as issues com o que não é tarefa.
• Templates — .github/ISSUE_TEMPLATE e PULL_REQUEST_TEMPLATE.md padronizam o que você precisa receber.

6. GitHub Actions: automação e CI/CD

Actions roda tarefas automaticamente quando algo acontece no repositório: um push, um PR aberto, uma tag criada, um horário do dia.

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  verificar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

Com isso, todo PR chega ao revisor já com lint, teste e build verificados. Os usos mais comuns:

• CI — testar e validar cada mudança.
• CD — publicar automaticamente ao mesclar na main.
• Agendado (on: schedule) — rotinas periódicas, como checar links quebrados ou atualizar dependências.
• Qualidade — cobertura, análise estática, verificação de licença.

Duas dicas que evitam dor: use secrets para credenciais (nunca escreva token no YAML) e fixe a versão das actions (@v4, ou melhor, o hash do commit) para não ser surpreendido por uma atualização de terceiro.

7. Releases, Pages e Packages

• Releases — empacotam uma tag com notas de versão e binários. É onde o usuário baixa a versão pronta, sem precisar entender Git.
• GitHub Pages — hospedagem estática grátis direto do repositório. Perfeito para documentação, landing page e portfólio.
• Packages — registro de pacotes (npm, Docker, Maven, NuGet) integrado às permissões do repositório.
• Gists — trechos de código avulsos, versionados, públicos ou secretos. Ótimos para compartilhar um script.

gh release create v1.2.0 --generate-notes
gh release upload v1.2.0 ./dist/app.zip

8. Segurança

O GitHub embute várias camadas de proteção — e a maioria é só ligar:

• Dependabot — abre PR automático quando uma dependência sua tem vulnerabilidade conhecida ou versão nova.
• Secret scanning — detecta token commitado e, em muitos casos, avisa o provedor para revogar.
• Code scanning (CodeQL) — análise estática procurando padrões de vulnerabilidade no seu código.
• Security advisories — canal privado para alguém reportar falha sem expor o problema ao mundo.
• 2FA obrigatório — desde 2023 para quem contribui com código na plataforma.

E do seu lado: use SSH ou token com escopo mínimo, nunca senha; e prefira fine-grained tokens, que dão acesso a repositórios específicos em vez de à conta inteira.

# Chave SSH: gere, adicione ao agente e cadastre a pública no GitHub
ssh-keygen -t ed25519 -C "voce@email.com"
ssh-add ~/.ssh/id_ed25519
gh ssh-key add ~/.ssh/id_ed25519.pub
ssh -T git@github.com    # testa a conexão

9. GitHub como portfólio

Para quem está construindo carreira, o perfil no GitHub costuma ser lido antes do currículo. O que realmente pesa:

1. README nos projetos. Um repositório sem README parece abandonado, por melhor que seja o código. Explique o problema, a solução, como rodar e o que você aprendeu.
2. Commits com mensagem de verdade. Um histórico de "update", "teste" e "asdf" diz muito sobre como você trabalharia em equipe.
3. Poucos projetos bem-feitos > muitos pela metade. Três repositórios completos valem mais que trinta tutoriais copiados.
4. README de perfil. Um repositório com o seu nome de usuário vira a página inicial do seu perfil.
5. Contribuição em projeto alheio. Um PR aceito em um projeto real mostra que você sabe trabalhar com o código dos outros — e vale mais que o gráfico de contribuições cheio.

Sobre o "quadradinho verde": consistência é boa, mas ninguém sério contrata por causa dele. Commit diário sem substância é fácil de identificar.

10. Alternativas e quando escolher outra

Para projeto pessoal, open source e portfólio, GitHub é a escolha padrão pelo alcance. Para empresa com exigência de dado on-premise, GitLab e Gitea auto-hospedados costumam entrar na conversa.

Resumindo

Git guarda a história do seu código. GitHub é onde essa história encontra outras pessoas — para revisar, automatizar, publicar e colaborar.

Se você está começando, o caminho mais curto para tirar proveito real:

1. Suba um projeto seu com README e licença.
2. Trabalhe em branches e abra PR mesmo estando sozinho — o hábito é o que conta.
3. Ligue um workflow simples de CI rodando os testes.
4. Ative o Dependabot.
5. Encontre uma issue good first issue em um projeto que você usa e mande seu primeiro PR.

O quinto passo é o que muda de patamar: é quando o GitHub deixa de ser um backup do seu código e vira o lugar onde você trabalha com o resto do mundo.