GitHub

Conceitos Fundamentais

Repositórios

copy# criar novo
gh repo create meu-projeto --public --clone
gh repo create meu-projeto --private --clone

# fork de repo alheio
gh repo fork alfredo-petri/docs --clone

# clonar
gh repo clone alfredo-petri/docs

# ver info
gh repo view
gh repo view alfredo-petri/docs --web

Configurações importantes

Issues

Sistema de tracking de tarefas, bugs e features.

copygh issue create --title "Bug: login falha com email inválido" --body "..."
gh issue list
gh issue list --label bug --assignee @me
gh issue view 42
gh issue close 42
gh issue reopen 42

# labels
gh label create priority/high --color F85149 --description "Alta prioridade"
gh label list

Labels padrão

Template de Issue

Crie .github/ISSUE_TEMPLATE/bug_report.md:

copy---
name: Bug Report
about: Reporte um bug
title: "[Bug] "
labels: bug
---

**Descrição**
Descrição clara do bug.

**Passos para reproduzir**
1. Vá para '...'

**Comportamento esperado**
O que deveria acontecer.

Pull Requests

Centro da colaboração no GitHub. Proposta de mudança revisada antes de mergear.

copygh pr create --title "feat: adicionar login" --body "Closes #42"
gh pr create --draft                     # rascunho (não pede review)
gh pr list
gh pr list --state merged
gh pr view 42
gh pr checkout 42                        # baixar branch do PR
gh pr diff 42
gh pr review 42 --approve
gh pr review 42 --comment "LGTM"
gh pr merge 42 --squash
gh pr merge 42 --rebase
gh pr merge 42 --merge
gh pr close 42

Status de PR

PR Template

.github/PULL_REQUEST_TEMPLATE.md:

copy## Descrição

## Tipo de mudança
- [ ] Bug fix
- [ ] Nova funcionalidade
- [ ] Refatoração

## Issues relacionadas
Closes #N

Code Review Workflow

Branch Protection Rules

copySettings → Branches → Add branch protection rule
  Branch name pattern: main

  ☑ Require a pull request before merging
    ☑ Require approvals (1)
    ☑ Dismiss stale reviews
  ☑ Require status checks to pass
  ☑ Require conversation resolution
  ☑ Require linear history (rebase only)
  ☑ Do not allow bypassing

GitHub Actions

CI/CD nativo. Workflows em YAML dentro de .github/workflows/.

Estrutura básica

copyname: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

Eventos (on)

Matrix builds

copystrategy:
  matrix:
    node: [18, 20, 22]
    os: [ubuntu-latest, windows-latest]
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}

Actions do marketplace

Secrets

copyUso no YAML:
  ${{ secrets.SSH_KEY }}
  ${{ vars.DEPLOY_PATH }}

CLI:
  gh secret set SSH_KEY < ~/.ssh/id_ed25519
  gh secret list
  gh secret remove SSH_KEY

Exemplo — Deploy

copyname: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd ~/apps/meu-app
            git pull origin main
            npm ci
            npm run build
            pm2 reload meu-app

GitHub Pages

Hospedagem gratuita de sites estáticos diretamente do repositório. Ideal para documentação, blogs, portfólios.

Tipos de site

Publicar Guias neste Repositório

Este repositório (alfredo-petri/docs) usa GitHub Pages para publicar os guias. Abaixo, as opções para configurar:

Opção A: Publicar da branch main — pasta /docs

Recomendada para este repositório. A estrutura exata — guias dentro de docs/ na branch main — é o caso de uso mais direto.

copySettings → Pages → Source: Deploy from a branch
  Branch: main
  Folder: /docs
  → Salvar

O site fica em: https://alfredo-petri.github.io/docs/

Opção B: Branch gh-pages separada

copygit checkout --orphan gh-pages
git rm -rf .
git add . && git commit -m "chore: publish docs"
git push origin gh-pages

Settings → Pages → Source: Deploy from a branch
  Branch: gh-pages
  Folder: / (root)

Opção C: GitHub Actions para Pages

Usa o workflow oficial actions/deploy-pages. Permite deploy com build (Jekyll, Vite, etc).

copyname: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/
      - id: deployment
        uses: actions/deploy-pages@v4

Configurar: Settings → Pages → Source: GitHub Actions

Opção D: Pages com build (Node.js)

Para projetos que geram HTML estático (Vite, Next.js export).

copyjobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build       # gera pasta dist/
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4

Publicar via GitHub CLI / API

O gh CLI não tem comando direto para Pages, mas existem várias formas de automatizar o deploy.

Opção 1: Push via subtree (mais simples)

Publica uma subpasta do repo direto para a branch gh-pages sem precisar de checkout separado.

copy# publicar pasta docs/ para branch gh-pages
git subtree push --prefix docs origin gh-pages

# forçar repush (se já existir)
git push origin `git subtree split --prefix docs`:gh-pages --force

Opção 2: gh-pages npm package

Faz push automático de uma pasta para a branch gh-pages.

copy# instalar
npm install -g gh-pages

# publicar pasta dist/ ou docs/
gh-pages -d docs

# com mensagem customizada
gh-pages -d dist -m "deploy: atualizar documentação"

# com dotfiles (arquivos ocultos)
gh-pages -d docs -t true

Opção 3: GitHub API (gh api)

Configura Pages via API REST.

copy# listar configuração atual
gh api repos/{owner}/{repo}/pages

# criar/configurar Pages (branch + pasta)
gh api -X POST repos/{owner}/{repo}/pages \
  -f build_type=legacy \
  -f source.branch=master \
  -f source.path=/docs

# habilitar Pages via API
gh api -X PUT repos/{owner}/{repo}/pages \
  -f build_type=legacy \
  -f source.branch=master \
  -f source.path=/docs

# listar builds de Pages
gh api repos/{owner}/{repo}/pages/builds

# forçar novo build
gh api -X POST repos/{owner}/{repo}/pages/builds

Opção 4: Trigger workflow existente

Se já tiver um workflow de deploy, execute via CLI.

copy# listar workflows
gh workflow list

# executar workflow específico
gh workflow run deploy-pages.yml

# com inputs
gh workflow run deploy-pages.yml \
  -f environment=production \
  -f ref=main

# listar execuções recentes
gh run list --workflow=deploy-pages.yml

# acompanhar execução em tempo real
gh run watch

Opção 5: Deploy via SSH + gh

Para servidores VPS — deploy manual via SSH após push.

copy# deploy completo: build + push + deploy remoto
npm run build && \
  git add -A && git commit -m "deploy" && git push && \
  ssh deployer@meuserver.com "cd ~/app && git pull && npm ci && npm run build && pm2 reload app"

# simplificado com gh secret
gh secret set SSH_KEY < ~/.ssh/id_ed25519

# em GitHub Actions:
- uses: appleboy/ssh-action@v1.0.3
  with:
    host: ${{ secrets.SSH_HOST }}
    username: ${{ secrets.SSH_USER }}
    key: ${{ secrets.SSH_KEY }}
    script: |
      cd ~/app
      git pull origin main
      npm ci && npm run build
      pm2 reload app

Comparativo

Domínio Personalizado

copySettings → Pages → Custom domain:
  → Digitar docs.alfredopetri.com
  → DNS: CNAME docs.alfredopetri.com → alfredo-petri.github.io
  → Enforce HTTPS → ON (após propagação DNS)

Ou criar arquivo CNAME na raiz:

copydocs.alfredopetri.com

404 personalizado

Crie 404.html na raiz do diretório publicado.

Resumo rápido — GitHub Pages

Dependabot

Monitora dependências com vulnerabilidades e abre PRs automaticamente.

copySettings → Code security → Dependabot
  ☑ Dependabot alerts   → ON
  ☑ Dependabot security updates → ON

.github/dependabot.yml:

copyversion: 2
updates:
  - package-ecosystem: npm
    directory: "/"
    schedule:
      interval: weekly
    open-pull-requests-limit: 10
    labels:
      - dependencies

Code Scanning (CodeQL)

Análise estática de segurança dentro do CI.

copyname: CodeQL

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: javascript
      - uses: github/codeql-action/analyze@v3

GitHub CLI (gh) — Avançado

copy# Navegação
gh browse                        # abrir repo no navegador
gh browse --settings

# Releases
gh release create v1.0.0 --title "v1.0.0" --notes "Changelog..."
gh release list
gh release download v1.0.0
gh release upload v1.0.0 asset.zip

# Gists
gh gist create arquivo.txt
gh gist list
gh gist view GIST_ID

# Search
gh search repos "topic:react"
gh search issues "label:bug" --repo user/repo
gh search prs --state open --author @me

# Secrets
gh secret list
gh secret set SSH_KEY < ~/.ssh/id_ed25519
gh secret remove SSH_KEY

# Config
gh config set editor nvim
gh config set git_protocol ssh

Discussions / Projects / Wiki

Discussions

Fórum do repositório (separado de Issues):

copySettings → Features → Discussions → ON

Categorias:
  └─ 📣 Announcements
  └─ 💡 Ideas
  └─ 🙏 Q&A
  └─ 💬 General

Projects (kanban)

Quadro de gerenciamento visual vinculado a Issues e PRs.

copygh project list
gh project view 1
gh project item-add 1 --url https://github.com/user/repo/issues/42

Wiki

Repositório separado de documentação:

copygit clone https://github.com/user/repo.wiki.git

Releases

Distribuição de versões com changelog e assets.

copygh release create v1.0.0 \
  --title "v1.0.0" \
  --notes "### Added\n- Feature X\n### Fixed\n- Bug Y" \
  --target main

# com assets
gh release create v1.0.0 dist/meu-app.zip --title "v1.0.0"

Referência Rápida