> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dados.rio/llms.txt
> Use this file to discover all available pages before exploring further.

# Criação de Pipelines

> Descrição do processo de criação de pipelines no Data Lake.

O repositório [prefect\_rj\_iplanrio](https://github.com/prefeitura-rio/prefect_rj_iplanrio) contém pipelines desenvolvidas com Prefect para automação de extração de dados da Prefeitura do Rio de Janeiro.

## Estrutura do projeto

### Raiz do repositório

```
pipelines/
├── rj_sec__pipeline1/
├── rj_sec__pipeline2/
└── ...
Dockerfile
pyproject.toml
```

### Pipeline

```
rj_sec__pipeline
├── Dockerfile
├── flow.py
├── prefect.yaml
├── pyproject.toml
└── ...
```

## Como usar o repositório

O repositório utiliza um modelo monorepo para gerenciar múltiplas pipelines Prefect de forma centralizada e padronizada:

* **Dockerfile base**: o arquivo `Dockerfile` na raiz define a imagem base utilizada por todas as pipelines. Ele inclui as dependências essenciais para execução dos fluxos, como Python, Prefect, drivers de banco de dados e ferramentas auxiliares. Cada pipeline pode customizar sua própria imagem a partir desse Dockerfile base, garantindo consistência e facilidade de manutenção.

* **`pyproject.toml` centralizado com uv workspaces**: o `pyproject.toml` na raiz do projeto gerencia as dependências Python de todas as pipelines utilizando [uv workspaces](https://github.com/astral-sh/uv).

  * Cada subdiretório em `pipelines/` representa um módulo Python independente, mas todos são importados automaticamente como membros do workspace.
  * As dependências e configurações definidas no `pyproject.toml` base são herdadas por todas as pipelines, facilitando a atualização e padronização do ambiente.
  * Novas pipelines adicionadas à pasta `pipelines/` são automaticamente reconhecidas e integradas ao workspace, sem necessidade de configuração manual adicional.

Esse modelo garante reprodutibilidade, isolamento e facilidade de evolução para todas as pipelines do repositório.

### Pipelines

Cada pipeline possui:

* `Dockerfile`: imagem customizada para execução no Prefect
* `flow.py`: definição dos fluxos Prefect
* `prefect.yaml`: configuração do deployment Prefect
* `pyproject.toml`: dependências específicas da pipeline

Alterações específicas de cada pipeline devem ser adicionadas no `Dockerfile` de cada pipeline, assim como dependências específicas devem ser adicionadas no `pyproject.toml` de cada pipeline.

O arquivo `prefect.yaml` é responsável por definir as configurações de deployment do flow Prefect. Esse arquivo especifica variáveis de ambiente, parâmetros, agendamento, infraestrutura de execução e outras opções necessárias para o correto funcionamento do fluxo. O arquivo também é utilizado nos workflows de CI/CD para registrar e disponibilizar os flows.

Consulte a [documentação oficial do Prefect](https://docs.prefect.io/v3/how-to-guides/deployments/prefect-yaml) para detalhes sobre todas as opções disponíveis.

### Templates

O repositório utiliza [`cookiecutter`](https://cookiecutter.readthedocs.io/) para facilitar a criação de novas pipelines de forma padronizada. Os templates disponíveis em `templates/` permitem gerar rapidamente a estrutura de diretórios e arquivos necessários para uma nova pipeline Prefect, incluindo `Dockerfile`, `flow.py`, `prefect.yaml` e `pyproject.toml`.

Para criar uma nova pipeline, instale `uv` e rode:

```sh theme={null}
uvx cookiecutter templates --output-dir=pipelines
```

Você será solicitado a informar valores como `secretaria` e `pipeline`, que serão utilizados para preencher os nomes dos diretórios, arquivos e variáveis nos templates.

## CI/CD

O repositório utiliza GitHub Actions para automatizar todo o ciclo de vida das pipelines, incluindo build, deploy e publicação de imagens Docker:

* **Deploy automático dos flows**: os workflows `.github/workflows/deploy-prefect-flows-prod.yaml` e `.github/workflows/deploy-prefect-flows-staging.yaml` realizam o deploy automático dos flows Prefect para os ambientes de produção e staging, respectivamente.

  * O workflow de produção é acionado a cada push na branch `master` ou manualmente, sempre que houver alterações em arquivos dentro de `pipelines/**`.
  * O workflow de staging é acionado a cada push em branches `staging/*` ou manualmente, também monitorando alterações em `pipelines/**`.
  * Ambos executam:
    * Checkout do código-fonte
    * Login no GitHub Container Registry (`ghcr.io`)
    * Instalação das dependências Python com `uv`
    * Execução do script `.github/scripts/deploy_prefect_flows.py`, que faz o deploy automático de todos os flows definidos em `pipelines/*/prefect.yaml`
    * Caso algum deploy falhe, o workflow é interrompido e o erro é registrado nos logs

* **Build e publicação da imagem Docker base**: o workflow `.github/workflows/build-and-push-root-dockerfile.yaml` é acionado em alterações no `Dockerfile` da raiz a cada push na branch `master`, além de poder ser executado manualmente. Ele realiza:

  * Build da imagem Docker definida no `Dockerfile` do repositório
  * Publicação da imagem no GitHub Container Registry (`ghcr.io/${{ github.repository }}:latest`)