Simplifique Seus Projetos: Como Usar Repositórios Template no GitHub

🚀 Cansado de configurar projetos do zero e copiar e colar os mesmos arquivos de workflow CI/CD vez após vez? Chega de retrabalho! Neste post, vamos resolver esse problema de uma vez por todas usando Repositórios Template do GitHub.

O Problema: Retrabalho Constante

Toda vez que você inicia um novo projeto, precisa:

1. ✅ Criar o repositório
2. ✅ Configurar .gitignore
3. ✅ Adicionar README.md padrão
4. ✅ Configurar workflows de CI/CD
5. ✅ Copiar configurações de linters (ESLint, Prettier, etc.)
6. ✅ Configurar estrutura de diretórios
7. ✅ Adicionar arquivos de licença
8. ✅ Configurar issue templates
9. ✅ Configurar pull request templates
10. ✅ E muito mais…

Se você tem 10 microsserviços para criar, isso significa repetir esse processo 10 vezes. E se você precisar atualizar algo? Boa sorte atualizando manualmente 10 repositórios!

O Custo Real

Vamos fazer as contas:

• Tempo por configuração inicial: ~30-60 minutos
• 10 repositórios: 5-10 horas de trabalho repetitivo
• Atualizações futuras: Multiplique esse tempo sempre que algo mudar

Isso é tempo que você deveria estar usando para criar valor, não copiando arquivos.

A Solução: GitHub Template Repositories

Repositórios Template são uma funcionalidade nativa do GitHub que permite criar um “molde” para novos projetos. Com um clique, você pode gerar um novo repositório com toda a estrutura, configurações e arquivos já prontos.

Benefícios Principais

✅ Economia de tempo brutal - De 1 hora para 30 segundos na criação de projetos
✅ Consistência garantida - Todos os projetos seguem os mesmos padrões
✅ Onboarding mais rápido - Novos desenvolvedores começam com estrutura familiar
✅ Manutenção centralizada - Atualize o template e novos projetos já começam atualizados
✅ Best practices embutidas - Force boas práticas desde o primeiro commit

Como Criar um Repositório Template

Passo 1: Criar o Repositório Base

Primeiro, crie um repositório normal com toda a estrutura que você quer replicar:

my-node-template/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml
│   │   ├── deploy.yml
│   │   └── security-scan.yml
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── pull_request_template.md
├── .vscode/
│   ├── settings.json
│   └── extensions.json
├── src/
│   ├── index.js
│   └── __tests__/
│       └── index.test.js
├── .gitignore
├── .eslintrc.js
├── .prettierrc
├── jest.config.js
├── package.json
├── README.md
├── LICENSE
└── CONTRIBUTING.md

Passo 2: Tornar o Repositório um Template

1. Vá para Settings do repositório
2. Na seção General, marque Template repository
3. Salve as mudanças

Pronto! Agora seu repositório é um template.

Passo 3: Usar o Template

Para criar um novo projeto a partir do template:

1. Vá até o repositório template
2. Clique em Use this template → Create a new repository
3. Defina o nome e configurações do novo repo
4. Clique em Create repository

Em segundos, você tem um novo repositório com toda a estrutura!

Exemplos de Templates Úteis

1. Template para API Node.js

node-api-template/
├── .github/workflows/
│   └── ci.yml              # Lint, test, build
├── src/
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   ├── middleware/
│   └── index.js
├── tests/
├── .env.example
├── .eslintrc.js
├── .prettierrc
├── jest.config.js
├── Dockerfile
├── docker-compose.yml
└── README.md

Workflow CI/CD incluído:

name: CI

on: [push, pull_request]

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

2. Template para Microserviço Python

python-microservice-template/
├── .github/workflows/
│   ├── ci.yml
│   └── deploy.yml
├── app/
│   ├── __init__.py
│   ├── main.py
│   └── routers/
├── tests/
├── .flake8
├── .pylintrc
├── pytest.ini
├── requirements.txt
├── requirements-dev.txt
├── Dockerfile
└── README.md

3. Template para Frontend React

react-app-template/
├── .github/workflows/
│   └── ci.yml
├── public/
├── src/
│   ├── components/
│   ├── hooks/
│   ├── pages/
│   ├── services/
│   ├── utils/
│   └── App.jsx
├── .eslintrc.json
├── .prettierrc
├── vite.config.js
├── tsconfig.json
└── package.json

Template vs Fork: Qual a Diferença?

Muita gente confunde Template com Fork. Aqui está a diferença:

Fork

• Mantém histórico Git completo do repositório original
• Conectado ao upstream - fácil sincronizar mudanças
• Ideal para contribuir com projetos open-source
• Mostra relação com o repo original no GitHub

Template

• Cria repositório limpo sem histórico do template
• Independente - sem conexão com o original
• Ideal para iniciar novos projetos
• Não mostra relação - é tratado como novo projeto

Use Template quando: Quer começar um projeto novo baseado em estrutura existente
Use Fork quando: Quer contribuir ou manter sincronizado com o original

Recursos Avançados de Templates

1. Variáveis Dinâmicas no README

Você pode usar placeholders que os usuários substituem:

# {{PROJECT_NAME}}

## Descrição
Este projeto é {{PROJECT_DESCRIPTION}}.

## Instalação
\`\`\`bash
git clone https://github.com/{{USERNAME}}/{{REPO_NAME}}
cd {{REPO_NAME}}
npm install
\`\`\`

2. Scripts de Inicialização

Inclua um script init.sh que configura o projeto:

#!/bin/bash
# init.sh

echo "🚀 Configurando novo projeto..."

# Solicita nome do projeto
read -p "Nome do projeto: " PROJECT_NAME

# Atualiza package.json
sed -i "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" package.json

# Gera .env a partir do exemplo
cp .env.example .env

# Instala dependências
npm install

# Primeiro commit
git add .
git commit -m "chore: initial commit from template"

echo "✅ Projeto $PROJECT_NAME configurado com sucesso!"

3. GitHub Actions para Validação

Inclua um workflow que valida o setup inicial:

name: Template Validation

on:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check for template placeholders
        run: |
          if grep -r "{{PROJECT_NAME}}" .; then
            echo "⚠️  Ainda existem placeholders não substituídos!"
            exit 1
          fi
      
      - name: Validate structure
        run: |
          required_files=".gitignore README.md package.json"
          for file in $required_files; do
            if [ ! -f "$file" ]; then
              echo "❌ Arquivo obrigatório não encontrado: $file"
              exit 1
            fi
          done

Best Practices para Templates

1. Documentação Clara

Seu README.md deve explicar:

• O que o template inclui
• Como usar o template
• Quais configurações precisam ser ajustadas
• Próximos passos após criar o projeto

# Node.js API Template

## 📦 O que está incluído

- ✅ Express.js configurado
- ✅ Jest para testes
- ✅ ESLint + Prettier
- ✅ GitHub Actions CI/CD
- ✅ Docker + docker-compose
- ✅ Estrutura de diretórios recomendada

## 🚀 Como usar

1. Clique em "Use this template"
2. Execute `npm install`
3. Copie `.env.example` para `.env`
4. Personalize as configurações
5. Comece a desenvolver!

## ⚙️ Configurações necessárias

- [ ] Atualizar nome do projeto em `package.json`
- [ ] Configurar variáveis de ambiente em `.env`
- [ ] Adicionar secrets no GitHub (se usar CI/CD)

2. Mantenha Atualizado

Templates desatualizados são piores que não ter template:

# Crie um workflow para dependabot
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

3. Múltiplos Templates por Stack

Organize templates por tecnologia/propósito:

my-org-templates/
├── node-api-template/
├── python-ml-template/
├── react-spa-template/
├── nextjs-app-template/
├── docker-compose-template/
└── terraform-aws-template/

4. Ambiente de Exemplo Funcional

O template deve ser funcional out-of-the-box:

{
  "name": "example-project",
  "scripts": {
    "dev": "nodemon src/index.js",
    "test": "jest",
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

Após clonar, npm install && npm run dev já deve funcionar.

Combinando Templates com Outras Ferramentas

Templates + Cookiecutter

Para projetos Python, combine com Cookiecutter:

cookiecutter gh:your-org/python-template

Templates + Yeoman

Para JavaScript, use Yeoman generators:

yo my-generator

Templates + Terraform Modules

Para infraestrutura:

module "api_service" {
  source = "github.com/my-org/terraform-api-module"
  
  app_name    = "my-api"
  environment = "production"
}

Casos de Uso Reais

1. Microsserviços Consistentes

Antes:

• Cada microsserviço tinha estrutura diferente
• Pipelines de CI/ CD inconsistentes
• Difícil para devs mudarem entre serviços

Depois (com template):

• Todos os 30 microsserviços seguem mesmo padrão
• CI/CD idêntico em todos
• Qualquer dev pode contribuir em qualquer serviço

2. Onboarding de Novos Projetos

Antes: 3-4 dias configurando projeto novo
Depois: 30 minutos usando template

3. Hackathons e Protótipos

Use templates para começar rápido:

• Template com autenticação pronta
• Template com dashboard básico
• Template com API CRUD completa

Limitações e Alternativas

Limitações dos Templates

1. Snapshot estático - Novos projetos não recebem atualizações do template automaticamente
2. Sem sincronização - Mudanças no template não se propagam
3. Customização manual - Ainda precisa ajustar alguns arquivos

Alternativas

Para manter sincronizado:

• Use Git subtrees ou submodules para código compartilhado
• Use Reusable Workflows (vimos no post anterior) para CI/CD
• Use npm packages para código comum

Para automação total:

• Cookiecutter (Python)
• Yeoman (JavaScript)
• Terraform (Infrastructure)

Conclusão: Menos Setup, Mais Código

Repositórios Template são uma das funcionalidades mais subestimadas do GitHub. Quando bem implementados, eles:

• ⏰ Economizam horas de trabalho repetitivo
• 🎯 Garantem consistência entre projetos
• 📚 Facilitam onboarding de novos desenvolvedores
• 🚀 Aceleram prototipagem e experimentação
• ✅ Forçam best practices desde o início

Checklist de Implementação

• Identifique padrões comuns nos seus projetos
• Crie template com estrutura base
• Adicione workflows de CI/CD
• Configure linters e formatters
• Escreva documentação clara
• Teste criando novos projetos
• Compartilhe com o time
• Mantenha atualizado

Próximos Passos

No próximo vídeo/post, vou mostrar:

• Templates avançados com inicialização automatizada
• Cookiecutter templates para personalização interativa
• Template + Terraform para infraestrutura como código
• Governança de templates em organizações

Recursos Úteis

• GitHub Template Repositories Docs
• Awesome GitHub Templates
• Cookiecutter Templates

Já usa repositórios template? Compartilha nos comentários como você os utiliza! Qual template seria mais útil para você?

#GitHub #Template #Productivity #DevOps #BestPractices