Como criar templates de repositório reutilizáveis no GitHub

1. Introdução aos templates de repositório no GitHub

Templates de repositório são modelos pré-configurados que permitem criar novos repositórios com uma estrutura padronizada, arquivos essenciais e configurações predefinidas. Diferentemente de forks, que mantêm um vínculo histórico com o repositório original, os templates geram cópias independentes e limpas, sem histórico de commits.

Os principais casos de uso incluem:
- Projetos base: Estruturas iniciais para novos projetos (Python, Node.js, Rust)
- Bibliotecas: Scaffolding com configuração de publicação (PyPI, npm)
- APIs: Templates com roteamento, middleware e testes configurados
- Configurações de equipe: Padronização de .gitignore, LICENSE e workflows de CI/CD

2. Configuração inicial de um repositório template

Para criar um template, siga estes passos:

  1. Crie um repositório público ou privado no GitHub
  2. Acesse Settings > General > Template repository e marque a opção
  3. Estruture os diretórios conforme o tipo de projeto

Estrutura recomendada para um template genérico:

meu-template/
├── src/
│   └── main.py
├── docs/
│   └── index.md
├── tests/
│   └── test_main.py
├── .github/
│   ├── workflows/
│   │   └── ci.yml
│   └── CODEOWNERS
├── .gitignore
├── LICENSE
├── README.md
└── setup.py

Boas práticas de organização:
- Use nomes descritivos para pastas (src/, app/, lib/)
- Mantenha a raiz limpa, com no máximo 5-7 arquivos
- Agrupe configurações em .github/ ou config/

3. Personalização de arquivos essenciais no template

O arquivo README.md deve conter instruções genéricas e placeholders:

# {{project_name}}

{{project_description}}

## Pré-requisitos
- Python 3.9+
- Node.js 18+

## Instalação
```bash
git clone https://github.com/{{username}}/{{project_name}}.git
cd {{project_name}}
pip install -r requirements.txt

Uso

python src/main.py

Licença

{{license}}


Arquivos de configuração padrão:

**`.gitignore`** (exemplo para Python):
```text
__pycache__/
*.pyc
.env
dist/
*.egg-info/

LICENSE (MIT simplificado):

MIT License

Copyright (c) {{year}} {{author}}

Permission is hereby granted...

CODEOWNERS:

* @{{team_lead}}
src/ @{{core_team}}
docs/ @{{docs_team}}

4. Automação com GitHub Actions e scripts de inicialização

Workflow de CI/CD reutilizável (.github/workflows/ci.yml):

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.9, 3.10, 3.11]

    steps:
    - uses: actions/checkout@v4
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v5
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Lint with flake8
      run: flake8 src/ tests/
    - name: Test with pytest
      run: pytest tests/

Script de setup automático (setup.sh):

#!/bin/bash
echo "Inicializando projeto..."
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
echo "Projeto configurado!"

5. Uso de placeholders e substituição dinâmica

Técnica com sed para substituir placeholders:

#!/bin/bash
# init.sh - Script para personalizar template

PROJECT_NAME=$1
AUTHOR=$2
YEAR=$(date +%Y)

if [ -z "$PROJECT_NAME" ]; then
    echo "Uso: ./init.sh <project_name> [author]"
    exit 1
fi

# Substituir placeholders nos arquivos
find . -type f -name "*.md" -o -name "*.py" -o -name "*.toml" | while read file; do
    sed -i "s/{{project_name}}/$PROJECT_NAME/g" "$file"
    sed -i "s/{{author}}/${AUTHOR:-Developer}/g" "$file"
    sed -i "s/{{year}}/$YEAR/g" "$file"
done

echo "Template personalizado para: $PROJECT_NAME"

Para projetos mais complexos, considere usar Cookiecutter:

# cookiecutter.json
{
    "project_name": "my-project",
    "author": "Developer",
    "python_version": "3.11",
    "use_docker": ["yes", "no"]
}

6. Documentação e boas práticas para usuários do template

No README.md, inclua um guia de uso claro:

## Como usar este template

### Pelo GitHub
1. Clique em "Use this template" no repositório
2. Preencha o nome do novo repositório
3. Clone o repositório criado

### Pela linha de comando
```bash
gh repo create meu-projeto --template usuario/template --public
cd meu-projeto

Checklist de personalização pós-clonagem

  • [ ] Alterar nome do projeto no README.md
  • [ ] Atualizar badges de status
  • [ ] Configurar secrets no GitHub (se aplicável)
  • [ ] Modificar pyproject.toml ou package.json
  • [ ] Ajustar links de documentação

## 7. Manutenção e atualização de templates ao longo do tempo

Estratégias de versionamento:

```text
main          → Versão estável (recomendada para novos projetos)
template-v2   → Versão em desenvolvimento
legacy        → Versão antiga (apenas correções críticas)

Para sincronizar alterações entre repositórios derivados:

# No repositório derivado
git remote add template https://github.com/usuario/template.git
git fetch template
git merge template/main --allow-unrelated-histories

Configure o Dependabot no template:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"

8. Exemplos práticos e considerações finais

Template para projetos Python (pyproject.toml):

[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "{{project_name}}"
version = "0.1.0"
description = "{{project_description}}"
authors = [{name = "{{author}}"}]
requires-python = ">=3.9"
dependencies = [
    "requests>=2.31",
    "pydantic>=2.0"
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4",
    "flake8>=6.0",
    "black>=23.0"
]

Template para APIs REST em Node.js (package.json):

{
  "name": "{{project_name}}",
  "version": "1.0.0",
  "description": "{{project_description}}",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js",
    "dev": "nodemon src/index.js",
    "test": "jest --coverage",
    "lint": "eslint src/"
  },
  "dependencies": {
    "express": "^4.18.0",
    "cors": "^2.8.5",
    "dotenv": "^16.0.0"
  },
  "devDependencies": {
    "jest": "^29.0.0",
    "supertest": "^6.0.0",
    "eslint": "^8.0.0"
  }
}

Armadilhas comuns a evitar:
- Credenciais fixas: Nunca inclua tokens, senhas ou chaves de API no template
- Permissões inadequadas: Configure permissões mínimas nos workflows do GitHub Actions
- Dependências desatualizadas: Use versões flexíveis (>=) em vez de fixas (==)
- Documentação genérica demais: Inclua exemplos reais de uso e personalização

Templates de repositório são ferramentas poderosas para padronizar e acelerar o desenvolvimento de projetos. Com as práticas descritas, você pode criar modelos reutilizáveis que economizam tempo, garantem consistência e facilitam a colaboração em equipe.

Referências