Pipelines de CI/CD

CI/CD para serviços Python executa ruff, pytest, build de imagem e deploy em estágios a cada merge. Pipelines aplicam os mesmos comandos que os desenvolvedores executam localmente com uv e fixam o Python 3.14.0 em matrizes de CI.

Receita

# .github/workflows/ci.yml (excerto)
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync --frozen
      - run: uv run ruff check .
      - run: uv run pytest -q

Quando usar isso:

Todo merge de equipe para main deve ter qualidade de candidato a deploy
Build de imagem Docker após a passagem dos testes
Promoção dev → staging → prod com aprovações
GitOps tag bump dispara rollout do cluster

Exemplo de Trabalho

GitHub Actions: teste, build/push de imagem, deploy em staging com OIDC para AWS.

name: ci-cd
on:
  push:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.14"
      - run: uv sync --frozen
      - run: uv run ruff check .
      - run: uv run pytest -q --cov=app
 
  build:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/ci-ecr-push
          aws-region: us-east-1
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: 123456789012.dkr.ecr.us-east-1.amazonaws.com/api:${{ github.sha }}
 
  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: echo "kubectl set image deployment/api api=...:${{ github.sha }}"

O que isso demonstra:

uv sync --frozen corresponde ao lockfile em CI
Assunção de role OIDC evita chaves AWS estáticas
Imagem com tag github.sha para rastreabilidade
Job de deploy bloqueado por regras de aprovação do environment: staging

Mergulho Profundo

Estágios do Pipeline

Estágio	Portões
Lint/teste	ruff, mypy opcional, pytest
Build	Dockerfile, scan de imagem
Deploy dev	automático em main
Deploy prod	aprovação manual + smoke test

Paridade Local/CI

uv run ruff check . && uv run pytest -q
docker build -t api:local .

Notas de Python

- run: uv run python -m build   # pacotes de biblioteca
- run: uv publish               # PyPI ao lançar libs, não serviços

Armadilhas

CI usa Python diferente do prod - bugs sutis. Correção: fixar 3.14 no workflow e na imagem Docker.
Pular testes em alterações apenas de documentação - filtros de caminho podem perder código acoplado. Correção: gatilhos conservadores ou regras de monorepo.
Tag de deploy :latest - rollback impossível. Correção: apenas tags SHA imutáveis.
Segredos no YAML do workflow - use segredos de Ambientes do GitHub e OIDC.
Sem smoke test pós-deploy - endpoint de saúde quebrado em produção. Correção: passo curl /health após o deploy.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
GitLab CI	Hospedagem GitLab	Organização apenas GitHub
Buildkite	Agentes auto-hospedados	GitHub Actions simples suficiente
ArgoCD GitOps	Detecção de drift de deploy K8s	Docker compose em VM única

FAQs

O que deve ser executado no prebuild?

Este repositório executa lint-docs no prebuild - mantenha a documentação válida ao enviar conteúdo com código.

uv vs pip em CI?

uv é mais rápido e nativo de lockfile - alinhe com o pin uv 0.6+ do manifesto.

Como faço cache de dependências?

setup-uv com cache habilitado ou montagens de cache do buildkit do Docker para a camada uv sync.

Migrações de banco de dados em CD?

Job separado antes da mudança de tráfego - nunca apenas na inicialização do aplicativo sem coordenação.

Como promovo staging para prod?

Retaguar o SHA testado ou reproduzir o job de deploy com aprovação do ambiente de produção - mesmo artefato, sem reconstrução.

Feature flags vs branches?

Trunk-based com flags é preferível; branches de ambiente de longa duração decaem.

Como executo testes de integração?

Marcador pytest com dependências de serviço docker-compose no job de CI ou ambiente de preview efêmero.

Caminhos de monorepo?

Filtros paths: por pacote - mas execute testes de todo o sistema em alterações de bibliotecas compartilhadas.

Como ruff 0.9+ se encaixa?

Ferramenta única para lint/formato - passo rápido de CI antes do pytest.

Estratégia de rollback?

Redeploy a tag de imagem anterior - documente no Runbook vinculado a Melhores Práticas de Deploy.

Relacionado

Dockerizando Python - build de imagem
Código de Infraestrutura de Teste - padrões de política de CI
Deploys Sem Interrupção - segurança de rollout
Configuração do pytest - layout de teste
Melhores Práticas de Deploy - checklist de pipeline

Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), 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+.

Pipelines de CI/CD

Receita

# .github/workflows/ci.yml (excerto)
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync --frozen
      - run: uv run ruff check .
      - run: uv run pytest -q

Quando usar isso:

Todo merge de equipe para main deve ter qualidade de candidato a deploy
Build de imagem Docker após a passagem dos testes
Promoção dev → staging → prod com aprovações
GitOps tag bump dispara rollout do cluster

Exemplo de Trabalho

GitHub Actions: teste, build/push de imagem, deploy em staging com OIDC para AWS.

name: ci-cd
on:
  push:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.14"
      - run: uv sync --frozen
      - run: uv run ruff check .
      - run: uv run pytest -q --cov=app
 
  build:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/ci-ecr-push
          aws-region: us-east-1
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: 123456789012.dkr.ecr.us-east-1.amazonaws.com/api:${{ github.sha }}
 
  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: echo "kubectl set image deployment/api api=...:${{ github.sha }}"

O que isso demonstra:

uv sync --frozen corresponde ao lockfile em CI
Assunção de role OIDC evita chaves AWS estáticas
Imagem com tag github.sha para rastreabilidade
Job de deploy bloqueado por regras de aprovação do environment: staging

Mergulho Profundo

Estágios do Pipeline

Estágio	Portões
Lint/teste	ruff, mypy opcional, pytest
Build	Dockerfile, scan de imagem
Deploy dev	automático em main
Deploy prod	aprovação manual + smoke test

Paridade Local/CI

uv run ruff check . && uv run pytest -q
docker build -t api:local .

Notas de Python

- run: uv run python -m build   # pacotes de biblioteca
- run: uv publish               # PyPI ao lançar libs, não serviços

Armadilhas

CI usa Python diferente do prod - bugs sutis. Correção: fixar 3.14 no workflow e na imagem Docker.
Pular testes em alterações apenas de documentação - filtros de caminho podem perder código acoplado. Correção: gatilhos conservadores ou regras de monorepo.
Tag de deploy :latest - rollback impossível. Correção: apenas tags SHA imutáveis.
Segredos no YAML do workflow - use segredos de Ambientes do GitHub e OIDC.
Sem smoke test pós-deploy - endpoint de saúde quebrado em produção. Correção: passo curl /health após o deploy.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
GitLab CI	Hospedagem GitLab	Organização apenas GitHub
Buildkite	Agentes auto-hospedados	GitHub Actions simples suficiente
ArgoCD GitOps	Detecção de drift de deploy K8s	Docker compose em VM única

FAQs

O que deve ser executado no prebuild?

Este repositório executa lint-docs no prebuild - mantenha a documentação válida ao enviar conteúdo com código.

uv vs pip em CI?

uv é mais rápido e nativo de lockfile - alinhe com o pin uv 0.6+ do manifesto.

Como faço cache de dependências?

setup-uv com cache habilitado ou montagens de cache do buildkit do Docker para a camada uv sync.

Migrações de banco de dados em CD?

Job separado antes da mudança de tráfego - nunca apenas na inicialização do aplicativo sem coordenação.

Como promovo staging para prod?

Retaguar o SHA testado ou reproduzir o job de deploy com aprovação do ambiente de produção - mesmo artefato, sem reconstrução.

Feature flags vs branches?

Trunk-based com flags é preferível; branches de ambiente de longa duração decaem.

Como executo testes de integração?

Marcador pytest com dependências de serviço docker-compose no job de CI ou ambiente de preview efêmero.

Caminhos de monorepo?

Filtros paths: por pacote - mas execute testes de todo o sistema em alterações de bibliotecas compartilhadas.

Como ruff 0.9+ se encaixa?

Ferramenta única para lint/formato - passo rápido de CI antes do pytest.

Estratégia de rollback?

Redeploy a tag de imagem anterior - documente no Runbook vinculado a Melhores Práticas de Deploy.

Relacionado

Dockerizando Python - build de imagem
Código de Infraestrutura de Teste - padrões de política de CI
Deploys Sem Interrupção - segurança de rollout
Configuração do pytest - layout de teste
Melhores Práticas de Deploy - checklist de pipeline

Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), 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+.

Pipelines de CI/CD

Buscar na documentação

Pipelines de CI/CD