Deploy técnico — GitHub Pages e distribuição

📦 Preparando o repositório para produção

Antes do primeiro deploy, o repositório precisa estar limpo, documentado e estruturado. Um .gitignore ausente vaza chaves; um README ausente trava o onboarding de novos colaboradores.

O que é

Preparar para produção é o conjunto de garantias mínimas — arquivos ignorados no controle de versão, README com instruções de uso, estrutura de pastas previsível — que permite que o repositório seja publicado, clonado e mantido sem fricção operacional.

🧱 Checklist pré-deploy

•.gitignore cobrindo .env, node_modules/, .DS_Store, dist/ e qualquer artefato local
•README.md com badge de deploy, link do site publicado, passos de instalação local
•LICENSE definido (MIT, Apache-2.0) — repositórios públicos sem licença bloqueiam reuso legal
•Estrutura previsível: curso/, assets/, index.html na raiz

.gitignore

# Secrets
.env
.env.local
*.key

# Build artifacts
dist/
build/
node_modules/

# OS
.DS_Store
Thumbs.db

# Editor
.vscode/
.idea/

💡 Por que aprender

O custo de um secret vazado em commit público é altíssimo — rotação de chaves, auditoria de acessos, possível invasão. Cinco minutos configurando .gitignore previnem horas de remediação.

🔑 Conceitos-chave

.gitignore antes do primeiro commit

Adicionar depois não remove segredos já versionados — exige reescrita de histórico

README como onboarding

Primeiro arquivo que um colaborador lê — define se ele consegue rodar localmente em 5 min

Licença explícita

Estrutura previsível

index.html na raiz é convenção esperada pelo GitHub Pages

⚙️ Configurando GitHub Pages

GitHub Pages serve arquivos estáticos diretamente do repositório — gratuito, com HTTPS e CDN global. Três decisões definem o setup: qual branch publica, qual diretório serve, se HTTPS está enforced.

O que é

GitHub Pages é o serviço de hospedagem estática integrado ao GitHub — publica HTML/CSS/JS diretamente de um branch e diretório do repositório em https://<org>.github.io/<repo>/ com CDN, HTTPS gratuito e suporte a domínio customizado.

Setup via gh CLI

# Criar repositório público
gh repo create inematds/triad --public --source=. --push

# Habilitar GitHub Pages no branch main, diretório raiz
gh api -X POST repos/inematds/triad/pages \
  -f source[branch]=main \
  -f source[path]=/

# Forçar HTTPS (sempre)
gh api -X PUT repos/inematds/triad/pages \
  -F https_enforced=true

# Verificar status
gh api repos/inematds/triad/pages

🎛️ As três decisões

1. Branch: main para projetos simples. Para builds, use gh-pages alimentado por CI.

2. Diretório: / (raiz) é o padrão. /docs isola conteúdo público do código.

3. HTTPS enforced: sempre true. Sem isso, o site é servido em HTTP e navegadores marcam como inseguro.

🔑 Conceitos-chave

Pages é estático

Não roda backend — só HTML/CSS/JS. Para lógica, use Cloudflare Workers ou Vercel Functions

HTTPS enforced sempre

Sem cost, sem trade-off — único motivo para não enforced é compatibilidade legada

URL previsível

<user>.github.io/<repo> — ou domínio custom via CNAME

CDN incluído

Fastly por trás — latência baixa global sem configuração

📁 Estrutura de arquivos para deploy correto

O erro mais comum em primeiro deploy: caminhos absolutos quebram quando o site é servido em subpath (/triad/ em vez de /). A regra é simples: paths relativos, index.html na raiz.

O que é

A estrutura de arquivos para deploy é o layout esperado pelo GitHub Pages — index.html na raiz do diretório servido, assets referenciados por caminhos relativos (./assets/) ou via <base> quando o site fica em subpath.

✗ Paths absolutos (quebram)

✗<link href="/style.css">
✗<img src="/assets/logo.png">
✗<a href="/curso/trilha1">
✗fetch("/api/data.json")

Em user.github.io/triad/, /style.css aponta para user.github.io/style.css — 404.

✓ Paths relativos (funcionam)

✓<link href="./style.css">
✓<img src="./assets/logo.png">
✓<a href="../trilha1/index.html">
✓fetch("./data.json")

Funciona em qualquer subpath — local, staging, produção.

Estrutura recomendada

triad/
├── index.html              # entrada — raiz do site
├── README.md
├── LICENSE
├── .gitignore
├── .github/
│   └── workflows/
│       └── deploy.yml      # CI/CD
├── curso/
│   ├── trilha1/
│   ├── trilha2/
│   ├── trilha3/
│   └── trilha4/
└── assets/
    ├── css/
    └── img/

🔑 Conceitos-chave

Path relativo por padrão

Funciona idêntico em local, staging e produção sem variáveis de ambiente

index.html na raiz

Convenção do Pages — outras pastas precisam do próprio index.html para pretty URLs

Subpath em projetos não-user

Repos de organização ficam em org.github.io/repo, não org.github.io

404.html opcional

Pages serve 404.html automaticamente para rotas inexistentes

🤖 Automatizando deploy com GitHub Actions

Push to main → deploy automático. GitHub Actions elimina o passo manual de buildar, copiar e publicar — todo commit em main vira release em produção em menos de 60 segundos.

O que é

GitHub Actions é o sistema de CI/CD nativo do GitHub — um workflow YAML em .github/workflows/ que dispara em eventos (push, PR, schedule), roda passos em runners gerenciados e publica artefatos. Para Pages, é o mecanismo oficial de deploy desde 2022.

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

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

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: '.'
      - id: deployment
        uses: actions/deploy-pages@v4

✗ Sem CI

✗Deploy manual — fácil esquecer
✗Estado do site ≠ estado do main
✗Sem trilha de auditoria de releases
✗Rollback exige saber o último estado bom

✓ Com CI

✓Push em main = deploy automático
✓Estado do site = estado do main, sempre
✓Histórico de runs com timestamp e SHA
✓Rollback = re-run de workflow anterior

💡 Por que aprender

Deploy manual é a fonte número um de drift entre código e produção. Quando o deploy é automático, o repositório se torna a única fonte de verdade — e o time confia que o que está em main está no ar.

🔑 Conceitos-chave

Workflow como código

YAML versionado junto com o projeto — quem revisa código revisa o pipeline

Concurrency: pages

Cancela deploy anterior se um novo chega — evita race condition

Permissions mínimas

Só pages: write e id-token: write — princípio do menor privilégio

workflow_dispatch

Permite re-deploy manual via UI sem precisar de novo commit

🏷️ Versionamento do sistema

Tags transformam commits anônimos em marcos rastreáveis. SemVer (MAJOR.MINOR.PATCH) comunica intenção: incompatível, novo recurso, correção — três palavras que orientam o consumidor a atualizar com confiança.

O que é

Versionamento semântico (SemVer) é a convenção vMAJOR.MINOR.PATCH — incrementa MAJOR em mudanças incompatíveis, MINOR em adições compatíveis, PATCH em correções. Combinado com git tag e gh release, cria pontos de restauração imutáveis.

📐 Como decidir o incremento

MAJOR v1.x.x → v2.0.0 — quebra compatibilidade. Estrutura de URLs mudou, formato do soul.md mudou, links antigos quebram.

MINOR v1.0.x → v1.1.0 — novo conteúdo compatível. Nova trilha, novo módulo, novos componentes sem quebrar nada existente.

PATCH v1.0.0 → v1.0.1 — correção. Typo, bug visual, link quebrado, ajuste de cor light-mode.

Fluxo de release

# Tag local anotada
git tag -a v1.0.0 -m "Initial release — 4 trilhas, 24 módulos"

# Publicar tag
git push --tags

# Criar release com notas
gh release create v1.0.0 \
  --title "TRIAD v1.0 — Initial release" \
  --notes "Primeira versão estável do curso TRIAD.

  Inclui:
  - Trilha 1 (Fundamentos) — 6 módulos
  - Trilha 2 (Técnica) — 6 módulos
  - Trilha 3 (Avançado) — 6 módulos
  - Trilha 4 (Escala) — 6 módulos

  Deploy: https://automationsai.net/triad/"

# Patch posterior
git tag -a v1.0.1 -m "Fix light-mode amber contrast"
git push --tags
gh release create v1.0.1 --notes "Ajuste de contraste WCAG AA em light mode"

🔑 Conceitos-chave

Tag anotada (-a)

Inclui autor, data, mensagem — diferente de lightweight tag que é só um ponteiro

Release ≠ Tag

Tag é git puro; Release é GitHub feature com notas, assets, discussão

SemVer comunica risco

PATCH é seguro; MAJOR exige migração — o número escolhido ensina como atualizar

Imutabilidade da tag

Reescrever tag publicada é veneno — força os consumidores a re-clonar

👥 Distribuindo para uma equipe

Deploy técnico só é completo quando outro humano consegue replicar o ambiente. O guia de onboarding é o contrato entre o sistema e o time — clone, instalar Hermes, configurar soul, validar.

O que é

O onboarding técnico é a sequência mínima de comandos que leva um colaborador de zero (máquina vazia) a operacional (Triad rodando localmente com soul carregado) em menos de 15 minutos — documentado como bloco copy-paste no README.

🛤️ Timeline do onboarding (15 min)

0–3 min

Clone + dependências base

Git, Node 20+, gh CLI autenticado

3–8 min

Instalar Hermes Agent

npm install -g hermes-agent + autenticação com chave Anthropic

8–12 min

Carregar soul.md

hermes init + apontar para o soul do projeto

12–15 min

Smoke test

Rodar tarefa de referência e validar saída SHIP do Crítico

Onboarding — bloco copy-paste do README

# 1. Clone
git clone https://github.com/inematds/triad.git
cd triad

# 2. Instalar Hermes globalmente
npm install -g hermes-agent

# 3. Autenticar com Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
hermes auth

# 4. Inicializar projeto e carregar soul
hermes init
hermes soul load ./soul.md

# 5. Smoke test — tarefa de referência
hermes run --task "Analise o mercado de cursos de IA"

# 6. Validar — deve retornar SHIP em <3 iterações
hermes status

💡 Por que aprender

Um sistema que só roda na máquina de quem construiu não escala. O onboarding como contrato testável — quinze minutos, comandos copy-paste, smoke test claro — é o que transforma o Triad de projeto pessoal em sistema de equipe.

🔑 Conceitos-chave

Smoke test obrigatório

Tarefa de referência confirma que cada peça funciona antes de uso real

Copy-paste > prosa

Comandos em bloco eliminam ambiguidade de "instale e configure"

Quinze minutos como benchmark

Acima disso, há fricção escondida — algum passo está implícito

Secrets fora do repo

Chave Anthropic em .env local — nunca em commit

📊 Monitorando uso após o deploy

Deploy sem métricas é deploy cego. Adoção real — quantas pessoas chegaram, quantas terminaram, de onde vieram — é o sinal que valida ou refuta o trabalho dos módulos anteriores.

O que é

Monitorar adoção é coletar e ler três fontes de sinal: tráfego GitHub (clones, views do repo), analytics web (visitantes únicos, páginas mais lidas, tempo na página) e taxa de conclusão (proxy: profundidade média de navegação dentro do curso).

📡 Três camadas de sinal

1. GitHub Traffic — gh api repos/inematds/triad/traffic/views retorna views únicas e totais dos últimos 14 dias. Indica curiosidade técnica.

2. Web Analytics — Cloudflare ou Plausible: visitantes únicos, top pages, referrers. Sem cookies, sem GDPR-pain. Indica adoção real.

3. Conclusão — profundidade de navegação. Quem chega no modulo-4-6 terminou o curso. Razão entre views do index e do último módulo = taxa de conclusão aproximada.

Plausible / Cloudflare Web Analytics no <head>

<!-- Plausible (self-hosted ou cloud) -->
<script defer
  data-domain="automationsai.net"
  src="https://plausible.io/js/script.js"></script>

<!-- OU Cloudflare Web Analytics -->
<script defer
  src='https://static.cloudflareinsights.com/beacon.min.js'
  data-cf-beacon='{"token": "abc123..."}'></script>

GitHub Traffic via gh CLI

# Views das últimas 2 semanas
gh api repos/inematds/triad/traffic/views

# Clones — quem está clonando para uso local
gh api repos/inematds/triad/traffic/clones

# Referrers — de onde estão chegando
gh api repos/inematds/triad/traffic/popular/referrers

# Páginas mais visitadas
gh api repos/inematds/triad/traffic/popular/paths

🎯 Benchmark inicial

Após o lançamento, monitore semanalmente por 4 semanas. Sinal saudável: visitantes únicos crescem, taxa de conclusão (último módulo / index) acima de 5%, referrers diversos (não só Twitter ou só LinkedIn).

🔑 Conceitos-chave

Analytics sem cookies

Plausible e Cloudflare evitam GDPR/LGPD pain — sem banner, sem consentimento

Conclusão como proxy

Razão último módulo / index é o sinal mais honesto sobre se o conteúdo segura atenção

GitHub Traffic ≠ Web Analytics

Um conta acessos ao repo, outro ao site — meça ambos para visão completa

Janela de 14 dias

GitHub Traffic mantém apenas últimas duas semanas — exporte se quiser histórico longo

✅ Resumo do Módulo

✓

Repositório pronto para produção — .gitignore, README, LICENSE e estrutura previsível são pré-requisitos não negociáveis

✓

GitHub Pages com HTTPS enforced — branch main, diretório raiz, sempre HTTPS. Hospedagem estática gratuita com CDN global

✓

Paths relativos sempre — caminhos absolutos quebram em subpath. index.html na raiz, assets via ./

✓

CI/CD com GitHub Actions — push em main vira deploy automático. Estado do site = estado do main, sempre

✓

SemVer + releases anotados — MAJOR.MINOR.PATCH comunica risco. Tags imutáveis criam pontos de restauração

✓

Onboarding de 15 min + analytics — guia copy-paste para a equipe, métricas de adoção para validar o investimento

Próximo Módulo:

4.6 — Onboarding não-técnicos: levando o Triad para quem não escreve código

← Voltar para Trilha 4 Próximo Módulo →