Task Time Sync — do Jira e Clockify para uma planilha que o time usa

Stack

• Python 3.11
• Pydantic
• SQLAlchemy
• Postgres (Supabase)
• Poetry
• GitHub Actions
• Backblaze B2
• Sentry
• Better Stack

Contexto

O time acompanhava tarefas no Jira e horas no Clockify, em lugares separados. A planilha Excel era o produto final que o time já usava, então o desafio era alimentá-la com dados confiáveis, todos os dias, sem trabalho manual.

Problema

Juntar duas APIs com identidades diferentes (o mesmo colaborador aparece com nomes distintos no Jira e no Clockify), manter a planilha e um banco relacional coerentes e avisar sobre prazos, sem que a falha de uma fonte derrubasse a execução inteira.

Decisões

• Excel é o produto. As fórmulas e os indicadores ficam na planilha; o pipeline só atualiza as tabelas de dados. O mesmo dado é espelhado em Postgres, para consultas relacionais.
• Uma fonte única para pessoas. A aba de funcionários é a única origem editável de identidade, compartilhada pela planilha e pelo banco. Isso normaliza responsáveis do Jira e usuários do Clockify para um mesmo nome. E-mails repetidos vão para uma aba de duplicados removidos, em vez de sobrescrever dados.
• Etapas isoladas. Jira, Clockify e alertas rodam separados. Uma indisponibilidade do Jira não impede a coleta do Clockify. Falhas são registradas e enviadas ao Sentry.
• Camadas com responsabilidade clara. Os clients só falam HTTP; as regras ficam nos services; modelos Pydantic validam os dados.
• Observabilidade barata. Um heartbeat no Better Stack confirma que a execução chegou ao fim.

Como funciona (uma execução, 7 passos)

1. Baixa a planilha do bucket.
2. Sincroniza funcionários no Postgres.
3. Coleta tarefas do Jira.
4. Coleta horas do Clockify.
5. Envia a planilha atualizada de volta.
6. Dispara alertas de prazo nos canais do Teams (8 webhooks, um por área).
7. Dispara o heartbeat.

Entrega e qualidade

• CI em todo push e pull request: pylint, verificação de formatação com black e pytest com cobertura enviada ao Codecov.
• Execução agendada todo dia às 06:50 (horário de Brasília) por workflow, com credenciais em secrets do repositório.
• Documentação própria, bilíngue, com arquitetura, modelo de dados e decisões de design.

Resultado

Um fluxo diário e automático que entrega a planilha atualizada e os alertas de prazo, sem intervenção manual. Por estimativa, evita cerca de 2 horas por dia de digitação manual de informações.

Limitações e próximos passos

O README não registra um percentual de cobertura de testes, e não há um script para obter o WORKSPACE_ID do Clockify (hoje ele vem da resposta da API). Dois pontos claros de melhoria.

Links