Linting em CI/CD
Portões de lint em CI bloqueiam merges quando o código viola regras de estilo, tipo ou segurança. Todo pull request recebe as mesmas verificações, independentemente da configuração do editor local.
Receita
# .github/workflows/lint.yml
name: lint
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
- run: uv sync --frozen --group dev
- run: uv run ruff check .
- run: uv run ruff format --check .
- run: uv run mypy src/Quando usar isso:
- Desenvolvedores pulam hooks de pre-commit
- Revisão de código pega formatação em vez de lógica
- Você precisa de evidências de auditoria de portões de qualidade
Exemplo de Trabalho
name: quality
on:
pull_request:
branches: [main]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
with:
python-version: "3.14"
- run: uv sync --frozen --group dev
- run: uv run ruff check .
- run: uv run ruff format --check .
- run: uv run mypy src/
- run: uv run pytest --cov=src --cov-fail-under=80
pre-commit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v5
- run: uv sync --frozen --group dev
- run: uv run pre-commit run --all-filesO que isso demonstra:
uv sync --frozengarante a integridade do lockfile- Passos separados de verificação e formatação para mensagens de erro claras
- mypy é executado apenas em
src/(não em testes) - Job opcional de pre-commit pega desenvolvedores que pulam hooks
Análise Detalhada
Pipeline de Lint em CI
| Passo | Comando | Falha em |
|---|---|---|
| Lint | ruff check . | Estilo, bugs, segurança |
| Formato | ruff format --check . | Código não formatado |
| Tipos | mypy src/ | Erros de tipo |
| Hooks | pre-commit run --all-files | Qualquer falha de hook |
Dicas de Desempenho
- Cache
.venvcom chave no hash do lockfile - Cache
.ruff_cachee.mypy_cache - Execute jobs de lint e teste em paralelo
Armadilhas
- Sem
--checkno formatador - CI comita formatação automaticamente. Correção:ruff format --checkfalha em vez de corrigir. - CI instala a versão mais recente do ruff - diferente do local. Correção: trave dependências de desenvolvimento em
uv.lock; use--frozen. - mypy sem dependências do projeto - erros de importação. Correção:
uv sync --group devantes do mypy. - Linting em
migrations/- falhas ruidosas em código gerado. Correção: exclua na configuração do ruff. - Verificações obrigatórias não aplicadas - PRs mergeiam apesar das falhas. Correção: regras de proteção de branch exigindo o job de lint.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Pre-commit.ci | Runner de hook gerenciado | CI auto-hospedada necessária |
| Reviewdog | Anotações inline em PR | Simples aprovação/reprovação é suficiente |
| SonarQube | Conformidade empresarial | Projetos pequenos |
FAQs
Lint e teste devem ser um único job?
Jobs separados rodam em paralelo e fornecem mensagens de falha mais claras.
Como faço cache do uv no GitHub Actions?
setup-uv cuida do cache. Use o hash de uv.lock como chave.
A CI deve corrigir a formatação automaticamente?
Não. Falhe e deixe o desenvolvedor corrigir localmente. Correção automática em CI esconde o problema.
Como faço lint apenas nos arquivos alterados?
Use ruff check $(git diff --name-only origin/main) para velocidade em repositórios grandes.
E quanto ao GitLab CI?
Mesmos comandos em um bloco script: após instalar o uv.
O branch main deve executar lint também?
Sim, em push para o main como uma rede de segurança. Verificações de PR são o portão principal.
Como adiciono um portão de cobertura?
pytest --cov-fail-under=80 no job de teste junto com o lint.
Posso pular o lint para PRs apenas de documentação?
Use filtros de caminho: paths-ignore: ['**.md'] no gatilho do workflow.
Como reporto resultados de lint em comentários de PR?
Ferramentas como reviewdog ou correspondentes de problemas do GitHub Actions anotam o diff.
E se o lint demorar muito?
Escopo do mypy para src/, cache agressivo, lint apenas em arquivos alterados em repositórios grandes.
Relacionados
- Configuração do Ruff - configuração do ruff
- Hooks de pre-commit - hooks locais
- mypy & pyright em CI - verificação de tipos
- Melhores Práticas de Linting e Formatação - política
Versões do Stack: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.