FluxoNovasFeatures

Integração Azure DevOps e SharePoint – pastas e documentação por Feature

Criação automática de pastas no SharePoint por Feature, preenchimento de Custom.LinkPastaDocumentacao e sincronização de anexos

Tempo real (webhooks) e varredura semanal (pipeline no Azure Repos)

Visão Geral • Instalação • Configuração • Pipelines • Testes • API

Índice

Visão Geral
Funcionalidades
Estrutura de pastas no SharePoint
Arquitetura
Tecnologias
Pré-requisitos
Instalação Rápida
Configuração
Uso
Estrutura do Projeto
Testes
API Endpoints
Pipeline e Service Hooks
Solução de Problemas
Referências
Licença

Visão Geral

O FluxoNovasFeatures integra Azure DevOps e SharePoint: a cada nova Feature (ou atualização com anexos), o sistema cria a estrutura de pastas no SharePoint, preenche o campo customizado Custom.LinkPastaDocumentacao no work item e sincroniza os anexos da Feature para a pasta.

Características principais

Tempo real: Service Hooks do Azure DevOps disparam a API ao criar/atualizar work items (Feature).
Pipeline principal (azure-pipelines.yml): varredura de Features, criação de pastas no SharePoint, link no work item e sincronização de anexos. Agendada toda segunda-feira às 05:00 (horário de Brasília); após a varredura completa inicial, processa só novas Features, novos anexos e movimentação para Closed.
Pipeline secundária (azure-pipelines-organize.yml): reorganização estrutural da pasta Projetos DevOps (Ano > Cliente > Feature, mesclar Qualiit → Quali It, remover duplicatas em 2020-2023). Sem agendamento — deve ser executada somente quando houver necessidade de organizar a pasta principal (ver Pipeline de organização).
Estrutura padronizada: {Base}/{Ano}/{Cliente}/{FeatureId} - {NumeroProposta} - {Título}.
Segurança: autenticação Microsoft Entra ID (MSAL) para SharePoint; PAT para Azure DevOps; validação de secret no webhook.

Funcionalidades

Criação de pastas

Criação em cadeia da pasta base e subpastas (Ano → Cliente → Pasta da Feature).
Nome do cliente normalizado (title case) a partir do Area Path.
Nome da pasta da Feature: {Id} - {NumeroProposta} - {Título} (sanitizado).

Link de documentação

Geração de link de compartilhamento (view, organization) no SharePoint.
Atualização do campo Custom.LinkPastaDocumentacao no work item da Feature.

Anexos

Listagem de anexos da Feature via API Azure DevOps.
Download e upload para a pasta da Feature no SharePoint (overwrite quando aplicável).

API e varredura

POST /webhook/devops: recebe eventos do Service Hook (work item created/updated).
GET /health: health check da API.
POST /sync/feature/{feature_id}: sincronização manual de uma Feature.
Script pipeline_feature_folders.py: ponto de entrada da varredura (usado pela pipeline principal).

Organização estrutural (Projetos DevOps)

Script script_estruturar_projetos_devops_once.py: reorganiza a pasta Projetos DevOps quando há pastas fora do padrão (ex.: empresas na raiz, conteúdo em 2020-2023). Move pastas para Ano > Cliente > Feature ID - Nº Proposta - Título, resolve Features no Azure DevOps (ID, Nº proposta ou título), mescla Qualiit em Quali It por ano e remove duplicatas em 2020-2023 quando a pasta canônica já existe no ano/cliente correto. Execução local ou via Pipeline de organização (sob demanda).
Consolidação (pipeline_consolidate_sharepoint.py): move pastas de origens configuráveis (Documentação dos Clientes, Documentação dos Projetos, etc.) para Projetos DevOps; roda apenas localmente (não na pipeline).

Estrutura de pastas no SharePoint

{Base} / {Ano} / {Cliente} / {FeatureId} - {NumeroProposta} - {Título}

Base: configurável (SHAREPOINT_FOLDER_PATH_BASE), ex.: Documentos Compartilhados/Projetos DevOps
Ano: ano de criação da Feature
Cliente: último segmento do Area Path, normalizado (ex.: CAMIL ALIMENTOS → Camil Alimentos)
FeatureId, NumeroProposta, Título: da Feature no Azure DevOps

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│  Azure DevOps (Service Hooks)  →  POST /webhook/devops       │
│  Pipeline (agendada)            →  pipeline_feature_folders  │
├─────────────────────────────────────────────────────────────┤
│  FastAPI (main.py)                                          │
│  • Validação webhook / sync manual                           │
│  • FeatureFolderService (orquestração)                       │
├─────────────────────────────────────────────────────────────┤
│  AzureDevOpsClient          │  SharePointFileService        │
│  • list_features, get_wi    │  • ensure_folder_path         │
│  • update_work_item_link    │  • create_sharing_link         │
│  • list_attachment_relations│  • upload_file                 │
│  • download_attachment      │  (auth: SharePointAuthService)│
└─────────────────────────────────────────────────────────────┘

Tecnologias

Tecnologia	Propósito
Python	3.10+
FastAPI	API HTTP (webhook, health, sync)
Pydantic / pydantic-settings	Configuração e validação
MSAL	Autenticação Microsoft Entra ID (SharePoint/Graph)
requests	Cliente HTTP (Azure DevOps, Microsoft Graph)

Pré-requisitos

Python 3.10+
Conta Azure DevOps: PAT com escopo Work Items (leitura e escrita para atualizar Custom.LinkPastaDocumentacao)
Microsoft Entra ID: aplicativo com permissões SharePoint/Graph (ex.: Sites.ReadWrite.All)
Site SharePoint: URL do site (ex.: https://qualiitcombr.sharepoint.com/sites/projetosqualiit)

Instalação Rápida

1. Clone o repositório

git clone https://dev.azure.com/qualiit/ALM/_git/Qualiit.FluxoNovasFeatures
cd Qualiit.FluxoNovasFeatures

2. Ambiente Python (backend)

cd backend
python -m venv .venv
.venv\Scripts\activate   # Windows
# source .venv/bin/activate   # Linux/macOS
pip install -r requirements.txt

3. Configuração

Copie backend/.env.example para backend/.env e preencha as variáveis (ver Configuração).

4. Executar a API

cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Health: GET http://localhost:8000/health
Sync manual: POST http://localhost:8000/sync/feature/{id}

Configuração

Crie o arquivo backend/.env (nunca commite; está no .gitignore). Use como base o backend/.env.example, que contém todas as variáveis necessárias para a Pipeline principal e para a Pipeline Consolidar. Os mesmos nomes devem ser usados ao configurar as variáveis no Azure DevOps (Pipelines → Variables).

Variáveis principais

Variável	Descrição	Secreto?
`AZURE_DEVOPS_PAT`	Personal Access Token do Azure DevOps	Sim
`AZURE_DEVOPS_ORG`	Organização (ex.: qualiit)	Não
`AZURE_DEVOPS_PROJECT`	Nome do projeto	Não
`SHAREPOINT_CLIENT_ID`	Client ID do app no Entra ID	Não
`SHAREPOINT_CLIENT_SECRET`	Client Secret	Sim
`SHAREPOINT_TENANT_ID`	Tenant ID do Entra ID	Não
`SHAREPOINT_SITE_URL`	URL do site SharePoint	Não
`SHAREPOINT_FOLDER_PATH_BASE`	Pasta base: Projetos DevOps (não incluir nome da biblioteca)	Não
`WEBHOOK_SECRET`	Secret para validar Service Hooks	Sim (recomendado)

Ver backend/.env.example e docs/CONFIGURAR_PIPELINE.md para instruções completas de configuração da pipeline.

Azure DevOps PAT

Azure DevOps → User settings → Personal access tokens → New Token
Escopo: Work Items (Read & write) para atualizar Custom.LinkPastaDocumentacao
Copie o token para AZURE_DEVOPS_PAT no .env

SharePoint (Entra ID)

Registre um aplicativo no Microsoft Entra ID (Azure Portal)
Permissões: Microsoft Graph → Sites.ReadWrite.All (ou escopo equivalente para SharePoint)
Crie um Client secret e preencha SHAREPOINT_CLIENT_ID, SHAREPOINT_CLIENT_SECRET, SHAREPOINT_TENANT_ID
SHAREPOINT_SITE_URL: URL do site SharePoint onde as pastas serão criadas

Uso

API (webhook + health + sync manual)

cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Health: GET http://localhost:8000/health
Sync manual: POST http://localhost:8000/sync/feature/12345 (substitua pelo ID da Feature)

Varredura (script)

cd backend
python pipeline_feature_folders.py

Lista todas as Features (Area Path configurado), garante pasta + link + anexos para cada uma.

Pipeline no Azure DevOps

Pipeline principal (azure-pipelines.yml): varredura de Features, pastas no SharePoint, link e anexos. Agendamento: toda segunda-feira às 05:00 (horário de Brasília), além de disparo manual.
Pipeline de organização (azure-pipelines-organize.yml): reorganização estrutural da pasta Projetos DevOps (igual ao script local). Sem agendamento — executar somente quando houver necessidade de organizar a pasta principal (ex.: após inclusão em massa de pastas antigas). Ver Pipeline de organização abaixo.

Instruções completas (criar pipeline, variáveis, executar): docs/CONFIGURAR_PIPELINE.md. Estrutura de pastas: docs/PIPELINES_RETRY_E_CONSOLIDAR.md.

Estrutura do Projeto

Qualiit.FluxoNovasFeatures/
├── backend/
│   ├── app/
│   │   ├── config.py              # Configurações (Pydantic Settings)
│   │   ├── models/                 # feature_folder, devops_models
│   │   ├── services/               # devops_client, sharepoint_auth, sharepoint_files, feature_folder_service
│   │   └── utils/                  # name_utils (normalização, sanitização)
│   ├── tests/                      # Testes unitários e de integração
│   ├── main.py                     # FastAPI: webhook, health, sync
│   ├── pipeline_feature_folders.py # Entrada da varredura (pipeline principal)
│   ├── script_estruturar_projetos_devops_once.py # Reorganização Projetos DevOps (pipeline organização)
│   ├── pipeline_consolidate_sharepoint.py        # Consolidação de pastas (apenas local)
│   ├── requirements.txt
│   ├── .env.example
│   └── pytest.ini
├── docs/
│   ├── CONFIGURAR_PIPELINE.md      # Instruções para configurar as pipelines
│   └── PIPELINES_RETRY_E_CONSOLIDAR.md  # Estrutura de pastas e retry/erros
├── azure-pipelines.yml             # Pipeline principal (varredura; segunda 05:00)
├── azure-pipelines-organize.yml    # Pipeline secundária (organização; só sob demanda)
├── README.md
└── README_DE_EXEMPLO.md

Testes

Testes unitários (não exigem .env)

cd backend
pip install -r requirements.txt
python -m pytest tests/ -v -m "not integration"

Cobre: name_utils, modelos feature_folder, feature_folder_service (conversões e datas), health da API.

Testes de integração (exigem .env preenchido)

Validam leitura/escrita no SharePoint (criar pasta, upload, link) e leitura no Azure DevOps (listar Features, obter work item, listar anexos). Não alteram dados reais além de uma pasta de teste no SharePoint.

cd backend
# Garanta que .env está preenchido (SharePoint e Azure DevOps)
python -m pytest tests/ -v -m integration

Se as variáveis não estiverem configuradas, os testes de integração são ignorados (skipped).

Todos os testes

cd backend
python -m pytest tests/ -v

API Endpoints

Método	Endpoint	Descrição
`GET`	`/health`	Health check (status da API)
`POST`	`/webhook/devops`	Recebe Service Hook (work item created/updated); valida `X-Webhook-Secret`
`POST`	`/sync/feature/{feature_id}`	Sincronização manual: pasta + link + anexos para a Feature

Pipeline e Service Hooks

Pipeline principal: Instruções passo a passo (criar, variáveis, executar) em docs/CONFIGURAR_PIPELINE.md. Agendamento: toda segunda-feira às 05:00 (horário de Brasília); disparo manual disponível. Estrutura de pastas e retry: PIPELINES_RETRY_E_CONSOLIDAR.md.
Pipeline de organização (secundária): usa o arquivo azure-pipelines-organize.yml. Executa o mesmo fluxo do script local script_estruturar_projetos_devops_once.py (reorganizar Projetos DevOps em Ano > Cliente > Feature, mesclar Qualiit → Quali It, remover duplicatas em 2020-2023). Não possui agendamento — deve ser rodada apenas quando houver necessidade de reorganizar a pasta principal (ex.: após migração ou inclusão em massa de pastas antigas). Criar em Pipelines → New pipeline → Existing Azure Pipelines YAML file → Path: /azure-pipelines-organize.yml; use as mesmas variáveis da pipeline principal.
Service Hooks (tempo real): Project Settings → Service hooks → Create subscription — eventos Work item created e Work item updated, URL https://<sua-api>/webhook/devops, header X-Webhook-Secret = valor de WEBHOOK_SECRET.

Solução de Problemas

Erro de autenticação Azure DevOps

Verifique AZURE_DEVOPS_PAT (não expirado, escopo Work Items).
Confirme AZURE_DEVOPS_ORG e AZURE_DEVOPS_PROJECT.

Erro ao acessar SharePoint

Confirme SHAREPOINT_SITE_URL, SHAREPOINT_CLIENT_ID, SHAREPOINT_CLIENT_SECRET, SHAREPOINT_TENANT_ID.
Verifique permissões do app no Entra ID (Sites.ReadWrite.All ou equivalente).

Webhook retorna 401

Configure WEBHOOK_SECRET no .env e o mesmo valor no header X-Webhook-Secret da subscription no Azure DevOps.

Testes de integração não rodam

Preencha o backend/.env com credenciais válidas; os testes de integração são skipped quando as variáveis estão vazias ou placeholder.

Referências

Licença

Repositório: Qualiit.FluxoNovasFeatures

Última atualização: 10/02/2026
Versão: 1.0.0
Backend: Python / FastAPI
Desenvolvido por: Marcelo Macedo
E-mail: marcelo.macedo@qualiit.com.br

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.github		.github
backend		backend
docs		docs
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
azure-pipelines-organize.yml		azure-pipelines-organize.yml
azure-pipelines.yml		azure-pipelines.yml

Folders and files

Latest commit

History

Repository files navigation

FluxoNovasFeatures

Integração Azure DevOps e SharePoint – pastas e documentação por Feature

Índice

Visão Geral

Características principais

Funcionalidades

Criação de pastas

Link de documentação

Anexos

API e varredura

Organização estrutural (Projetos DevOps)

Estrutura de pastas no SharePoint

Arquitetura

Tecnologias

Pré-requisitos

Instalação Rápida

1. Clone o repositório

2. Ambiente Python (backend)

3. Configuração

4. Executar a API

Configuração

Variáveis principais

Azure DevOps PAT

SharePoint (Entra ID)

Uso

API (webhook + health + sync manual)

Varredura (script)

Pipeline no Azure DevOps

Estrutura do Projeto

Testes

Testes unitários (não exigem .env)

Testes de integração (exigem .env preenchido)

Todos os testes

API Endpoints

Pipeline e Service Hooks

Solução de Problemas

Erro de autenticação Azure DevOps

Erro ao acessar SharePoint

Webhook retorna 401

Testes de integração não rodam

Referências

Licença

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages