CI/CD para Flask: automatize o Deploy da sua API com Docker e GitHub Actions

Bora acabar com isso agora!

O que você vai construir

• Detecta mudanças no seu código automaticamente

• Cria uma imagem Docker otimizada da sua aplicação

• Faz o push dessa imagem para um registro (Docker Hub)

• Deixa tudo pronto para o deploy em qualquer ambiente

O que você precisa saber antes

• Conhecimento básico de Python e Flask

• Familiaridade com Docker (saber criar um container básico)

• Uma conta no GitHub

• Uma conta no Docker Hub (para armazenar suas imagens)

• Vontade de automatizar suas entregas

Bora começar? 🚀

Entendendo CI/CD

CI: Continuous Integration (integração contínua)

CD: Continuous Delivery ou Continuous Deployment (entrega ou deploy contínuo)

• Continuous Delivery (entrega contínua): significa que seu código está testado, empacotado e pronto para ir para produção a qualquer momento. O deploy final ainda pode ser manual, mas o pacote está pronto.

• Continuous Deployment (deploy contínuo): leva isso um passo adiante. Se o código passar por todos os testes, ele é automaticamente enviado para produção, sem intervenção humana.

Preparando a API Flask

Estrutura do projeto

flask-cicd-pipeline/
├── app.py
└── requirements.txt

O código da API

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/')
def index():
    return jsonify({"message": "Deploy automatizado funcionando! 🚀", "status": "success"})

# O bloco abaixo só é usado local.
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000, debug=True)

Dependências

Flask>=3.0.0
gunicorn

Criando o Dockerfile

# 1. Imagem base: Começamos com uma imagem Python oficial e leve.
# 'slim' significa que ela tem apenas o necessário para rodar Python.
FROM python:3.11-slim

# 2. Diretório de trabalho: Define onde o código vai ficar dentro do container.
WORKDIR /app

# 3. Instalação de dependências:
# Copiamos apenas o requirements.txt primeiro. Isso otimiza o cache do Docker.
# Se o código mudar, mas os requisitos não, essa etapa não precisa ser refeita.
COPY requirements.txt .

# Rodamos o pip para instalar as dependências.
# '--no-cache-dir' ajuda a manter a imagem final menor.
RUN pip install --no-cache-dir -r requirements.txt

# 4. Código da aplicação: Copiamos o restante dos arquivos do nosso projeto.
COPY . .

# 5. Exposição de porta: Informamos ao Docker que nossa aplicação vai usar a porta 5000.
EXPOSE 5000

# 6. Comando de inicialização: O que o container deve fazer quando iniciar.
# Usamos gunicorn para servir nossa aplicação Flask.
# '--bind 0.0.0.0:5000' faz a aplicação escutar em todas as interfaces na porta 5000.
# 'app:app' diz ao gunicorn para procurar o objeto 'app' dentro do módulo 'app.py'.
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

Como testar o container localmente

1. Build da imagem: No terminal, dentro da pasta do projeto, rode o comando para construir a imagem. Vamos chamá-la de flask-api-cicd.

docker build -t flask-api-cicd .

docker run -p 5000:5000 flask-api-cicd

Configurando o GitHub Actions

Componentes principais

• Workflow: o processo automatizado completo que você define.

• Trigger (gatilho): o evento que inicia o workflow (ex: um push na branch main).

• Job: um conjunto de passos que rodam em um ambiente.

• Step (passo): uma tarefa individual dentro de um job (ex: rodar um comando).

Criando o arquivo de workflow

flask-cicd-pipeline/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── app.py
├── Dockerfile
└── requirements.txt

Configuração do workflow

name: CI/CD Pipeline - Build and Push Docker Image

# Triggers: Define quando o workflow será executado
on:
  push:
    branches: [ "main" ] # Apenas na branch main
  pull_request:
    branches: [ "main" ] # Também roda quando um PR for aberto contra a main

# Jobs: Os trabalhos que serão executados
jobs:
  build-and-push:
    # Define o ambiente onde o job vai rodar (uma máquina virtual Ubuntu)
    runs-on: ubuntu-latest

    # Steps: Os passos do job
    steps:
    # Passo 1: Checkout do código
    # Usa uma action pronta para baixar o código do repositório para a máquina virtual
    - name: Checkout code
      uses: actions/checkout@v4

    # Passo 2: Login no Docker Hub
    # Precisamos fazer login para poder enviar a imagem para o registro
    - name: Login to Docker Hub
      # Só executa este passo se for um push na main (não em PRs)
      if: github.event_name == 'push'
      uses: docker/login-action@v3
      with:
        # Usamos secrets do GitHub para armazenar credenciais de forma segura
        username: ${{ secrets.DOCKERHUB_USERNAME }}
        password: ${{ secrets.DOCKERHUB_TOKEN }}

    # Passo 3: Configurar o Docker Buildx
    # Buildx é uma ferramenta avançada do Docker para builds mais eficientes
    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3

    # Passo 4: Build e Push da imagem
    # A action principal que faz o trabalho pesado
    - name: Build and push Docker image
      uses: docker/build-push-action@v5
      with:
        context: . # Onde está o Dockerfile (na raiz)
        # Só faz o push se for um push na main. Em PRs, apenas faz o build (para verificar se funciona)
        push: ${{ github.event_name == 'push' }}
        # Define o nome e a tag da imagem. Ex: seuusuario/flask-api-cicd:latest
        tags: ${{ secrets.DOCKERHUB_USERNAME }}/flask-api-cicd:latest

Explicação do workflow

• Adicionamos pull_request nos triggers. Isso é uma boa prática de CI: verificar se o código do PR consegue ser integrado antes do merge.

• Usamos if: github.event_name == 'push' para garantir que o login e o push para o Docker Hub só aconteçam quando o código for efetivamente enviado para a main, não durante a verificação de um PR.

Secrets e variáveis de ambiente

1. Crie um token no Docker Hub:
• Vá em Docker Hub > Account Settings > Security.
• Clique em "New Access Token".
• Dê um nome (ex: "github actions token") e gere o token.
• Importante: Copie ele agora! Você só verá ele uma vez.

2. Configure no GitHub:
• No seu repositório no GitHub (você precisará subir o código que criamos até agora), vá em Settings > Secrets and variables > Actions.
• Clique em "New repository secret".
• Crie DOCKERHUB_USERNAME com seu nome de usuário do Docker Hub.
• Crie DOCKERHUB_TOKEN com o token que você copiou do Docker Hub.

Testando o pipeline

Como fazer um commit que vai acionar o workflow

1. Certifique-se de que seu projeto está no GitHub.

2. Faça uma pequena alteração (opcional). Se quiser testar a atualização, mude a mensagem no app.py:

3. Commit e Push: Certifique-se de que todos os arquivos (incluindo o diretório .github/workflows) foram adicionados e faça o push para a branch main.

Onde visualizar os logs no GitHub Actions

1. Vá para a aba "Actions" no seu repositório do GitHub.

2. Você verá seu workflow listado, provavelmente com um ícone amarelo indicando que está em execução.

3. Clique nele para ver os detalhes e acompanhar os logs de cada step em tempo real.

Como interpretar sucessos e falhas

• Sucesso (Verde ✅): Parabéns! Sua imagem Docker foi construída e enviada para o Docker Hub.

• Falha (Vermelho ❌): Não se preocupe. Clique no passo que falhou para ler os logs. O GitHub Actions fornece logs detalhados que geralmente apontam a causa do problema.

Debug de problemas comuns

• Falha no login do Docker Hub: verifique se as secrets (DOCKERHUB_USERNAME e DOCKERHUB_TOKEN) estão corretas no GitHub. Lembre-se que o token não é sua senha normal.

• Falha no build: pode haver um erro no seu Dockerfile ou no código da aplicação. Leia os logs do step "Build and push Docker image". Teste o build localmente primeiro.

• Workflow não inicia: verifique se o arquivo está em .github/workflows/deploy.yml e se o trigger está configurado para a branch correta (main).

Próximos passos e melhorias

Adicionar testes automatizados

Implementar diferentes ambientes