Automatize o Carimbo de Data/Hora de Commits do Git com um GitHub App
Você decidiu que seus commits merecem prova criptográfica de existência. Ótimo. Agora a única questão que importa operacionalmente é esta: essa prova acontece quando você pensa nisso, ou acontece todas as noites, quer alguém pense nisso ou não?
A primeira versão de qualquer processo de carimbo de data/hora é manual. Alguém da equipe escreve um script, executa-o antes de um release, salva um arquivo em algum lugar e se sente razoavelmente protegido. Seis semanas depois, essa pessoa está de férias, o script está em um laptop que foi reformatado, e a branch de release nunca foi carimbada. Pior ainda, ninguém percebe — porque um repositório com cobertura parcial de carimbos de data/hora parece exatamente igual a um totalmente coberto até que um auditor pergunte sobre uma data específica.
Este artigo trata do caminho da automação: uma instalação, nenhum ritual por commit, nenhuma ferramenta nas máquinas dos desenvolvedores. Abordaremos a configuração única, o que realmente acontece entre um git push e um bloco Bitcoin, como monitorar esse pipeline e onde a automação pode falhar silenciosamente.
A Armadilha do Carimbo Manual (e Por Que a Automação Vence)
O carimbo de data/hora manual tem um modo de falha previsível: ele escala com disciplina, e disciplina não escala entre equipes, repositórios e fusos horários.
Concretamente, a abordagem manual significa executar uma etapa de CLI ou um script sob medida para cada commit com que você se importa — ou pior, montar à mão os dados da transação Bitcoin subjacente. Esse é o caminho difícil, e ele quebra em três pontos:
- É por commit. Cem commits por semana se tornam cem oportunidades de pular a etapa.
- Depende do ambiente. O script vive na máquina de alguém, não na história do repositório. Novos contratados não o têm; a CI não o tem por padrão.
- É inverificável como política. A conformidade não consegue dizer se um carimbo está faltando porque nada aconteceu naquele dia ou porque alguém esqueceu.
Para os desenvolvedores, o requisito é simples: nada muda no meu fluxo de trabalho. Para a conformidade, o requisito é igualmente simples: todo commit em todo repositório monitorado está coberto, e eu posso provar isso.
Esse é o argumento para um GitHub App como superfície de automação em vez de uma CLI. O GitHub App do Timestamp GIT é instalado uma vez no nível da organização e então observa cada commit nos repositórios que você selecionar, ancorando-os ao Bitcoin todas as noites — muito depois de todos terem ido para casa.
Configuração Única: Instale o GitHub App e Esqueça
A configuração é uma única passada, feita por um administrador em vez de cada desenvolvedor.
- Instale o App na sua organização do GitHub ou conta pessoal.
- Selecione os repositórios a monitorar. Não há arquivo de configuração por repositório, nenhuma alteração na CI e nenhuma instalação na máquina do desenvolvedor.
- Conceda permissões. O sistema de permissões do GitHub não oferece um escopo “apenas hash de commit”, então o App precisa de acesso somente leitura aos seus repositórios de código-fonte e acesso leitura-escrita ao repositório de destino onde as provas são gravadas. Esse destino de leitura-escrita é ou uma branch
timestampsdedicada no mesmo repositório, ou um repositório-sombra separado — você decide. - Pronto. A partir daqui, a detecção roda via webhooks do GitHub e nada mais é exigido da sua equipe.
Se você quiser o modelo de isolamento mais rígido, o modo Enterprise ZK troca a detecção por webhook por uma GitHub Action de 12 linhas que executa na sua própria infraestrutura. Essa Action envia apenas o hash do commit para a API do Timestamp GIT. Nesse modo, o serviço não exige nenhum acesso de leitura aos seus repositórios de código-fonte — apenas acesso leitura-escrita ao repositório de destino que recebe as provas. Você precisa, é claro, instalar a própria Action.
Auto-hospedagem em ambiente isolado ou de alta segurança
Para controle máximo, o Timestamp GIT é distribuído como uma imagem Docker sob uma licença auto-hospedada. Uma configuração rápida de Docker Compose se parece com isto:
services:
timestampgit:
image: rue1401/timestampgit:prod
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped
valkey:
image: valkey/valkey:8
restart: unless-stopped
Suba e acompanhe os logs:
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
A aplicação fica disponível em http://localhost:8080 assim que iniciar. Na primeira execução, um assistente de configuração guia você pela conexão do seu GitHub App e pela configuração da instância. A avaliação roda com uma licença de demonstração por tempo limitado, solicitada na página de Licença Docker com seu nome, empresa, e-mail e, opcionalmente, um número de telefone.
Dentro do Pipeline Automatizado: Do Commit à Âncora Bitcoin
Uma vez instalado, o pipeline é despretensioso por design. Esse é o ponto — ele deve ser entediante.
1. Detecção de commits. O GitHub App captura novos commits via webhooks. No modo Enterprise ZK, sua GitHub Action envia os hashes para a API. De qualquer forma, apenas hashes de commit trafegam.
2. Fila de hashes. Os hashes chegam a um armazenamento chave-valor em memória e aguardam o próximo lote. Isso é deliberado: agrupar centenas de commits em uma única âncora Bitcoin é o que torna a coisa toda barata o suficiente para rodar em todos os repositórios que você possui.
3. Worker cron da meia-noite. A cada noite, um worker agrupa todos os hashes pendentes, grava um arquivo de manifesto por repositório (.txt), constrói uma árvore de Merkle nativamente, cria provas OpenTimestamps contra calendários OTS públicos e ancora a raiz de Merkle na blockchain do Bitcoin.
4. Entrega das provas. O manifesto e os arquivos de recibo .ots são enviados de volta ao seu repositório — para uma branch timestamps dedicada ou um repositório-sombra. A confirmação do Bitcoin normalmente leva cerca de 3 horas, então a gravação das provas geralmente termina algumas horas após o início do lote.
A chamada de API que o modo ZK faz se parece com isto (o segmento {hash} é o valor HMAC da URL assinada, não um hash de commit):
curl -X POST \
"https://timestampgit.dev/api/timestamp/acme/payments-api/proofs/<hmac>/<commit-sha>/<commit-id>"
Observe o que não está nesse payload: nenhum diff, nenhum conteúdo de arquivo, nenhum nome de branch, nenhuma identidade de autor além do que um ID de commit implica. A segurança de conhecimento zero aqui não é uma frase de marketing — o serviço nunca vê, copia ou armazena seu código-fonte, apenas o hash do Git.
E observe o que não é exigido dos seus desenvolvedores: nenhum comando, nenhum hook, nenhuma flag. Eles fazem push como de costume. A prova aparece na manhã seguinte.
Monitoramento e Tratamento de Falhas: Mantendo Suas Provas Confiáveis
Automação que você não consegue observar é apenas esperança com etapas extras. Há três níveis de visibilidade, e você deve usar todos eles.
Painéis públicos de status
Todo repositório monitorado ganha uma página de status em https://timestampgit.dev/status/{user}/{repo} mostrando a longevidade das provas (até onde a cobertura retrocede), a data da âncora mais antiga, a regularidade diária, os dados do bloco e da transação Bitcoin e um mapa de calor em calendário. O mapa de calor é a forma mais rápida de detectar uma lacuna: um único dia faltante se destaca imediatamente.
Badges no README
Pegue o widget de incorporação em https://timestampgit.dev/connected/{user}/{repo}, que fornece uma prévia ao vivo do Shields.io mais Markdown pronto para copiar e colar. O badge leva a uma página pública de verificação que qualquer pessoa pode conferir — útil quando você quer que um cliente ou auditor confirme a cobertura sem criar uma conta.
# Returns badge URLs and ready-to-paste markdown snippets
curl https://timestampgit.dev/api/badgeLink/acme/payments-api
Repositórios privados também são tratados: suas URLs carregam um HMAC criptografado, específico da instância do servidor, de modo que apenas usuários autorizados podem ler o status.
Monitoramento programático e exportações de auditoria
Os endpoints públicos de status são projetados para serem consultados pela sua própria ferramenta:
# Last anchored Bitcoin block info (JSON)
curl https://timestampgit.dev/api/statusLast/acme/payments-api
# Total committed / stamped commit count (JSON)
curl https://timestampgit.dev/api/statusCount/acme/payments-api
# Combined summary used by Shields.io
curl https://timestampgit.dev/api/statusSummary/acme/payments-api
Para relatórios de conformidade, obtenha o livro-razão completo de auditoria em CSV com GET /api/audit/{user}/{repo} e certificados PDF por dia com GET /api/report/{user}/{repo}/{date}.
Quando uma execução falha
Se uma execução noturna atrasar ou falhar, os hashes pendentes permanecem na fila e entram no próximo lote — os commits não são descartados. Na prática, o sintoma de um problema é um trecho plano no mapa de calor de status, em vez de dados perdidos. Observe em dois lugares: docker compose logs -f timestampgit para instâncias auto-hospedadas, e o painel para o SaaS.
Boas Práticas para o Carimbo Automatizado de Commits
A automação elimina o custo por commit, então o padrão correto muda: a cobertura deve ser ampla, não curada.
- Monitore todo repositório que contenha propriedade intelectual. Escolher a dedo repositórios “importantes” é uma decisão manual disfarçada de automação — e o repositório que você pula é sempre o que acaba importando. O custo marginal de outro repositório é um hash noturno em um lote existente.
- Use o modo Enterprise ZK para bases de código sensíveis. Se sua política diz que os próprios hashes de commit não devem transitar por terceiros, a rota da GitHub Action mantém tudo, exceto o hash, dentro do seu perímetro. Para ambientes totalmente isolados, a licença Docker auto-hospedada cobre o mesmo terreno.
- Exporte livros-razão de auditoria em uma agenda. Um CSV na mesma pasta dos seus documentos jurídicos vale mais do que um login de painel que você vai esquecer durante uma disputa.
- Faça commits cedo e com frequência nas branches monitoradas. Muitos commits pequenos dão uma trilha de provas mais densa, com datas mais defensáveis, do que um único squash grande no momento do release.
- Evite reescrever o histórico em branches das quais você depende para anterioridade. Um force-push cria novos hashes; os antigos permanecem ancorados, mas o mapeamento entre “este código” e “esta prova” fica mais difícil de explicar a um advogado. Se precisar reescrever, marque com tag o estado anterior à reescrita primeiro.
- Mantenha a branch de provas separada das suas branches de código-fonte. A branch
timestampsou o repositório-sombra é saída gerada — tratá-la como somente leitura evita merges acidentais namain.
Uma fronteira a ter em mente: o agrupamento em lotes mais cerca de 3 horas de confirmação do Bitcoin significa que um commit feito às 17h não é provável às 17h05. Se você precisa de prova hoje, planeje em torno da janela noturna em vez de esperar liquidação instantânea.
FAQ
Os desenvolvedores precisam executar algum comando ou instalar ferramentas para carimbar commits?
Não. Uma vez instalado o GitHub App, todo commit em um repositório monitorado é automaticamente detectado e ancorado ao Bitcoin todas as noites. Os desenvolvedores continuam usando o Git como de costume — sem CLI, sem etapas manuais.
Quanto tempo após um commit a prova de carimbo de data/hora fica disponível?
Os commits são agrupados e ancorados uma vez por noite. Após o envio do lote, a confirmação do Bitcoin normalmente leva cerca de 3 horas, então as provas geralmente ficam disponíveis na manhã seguinte.
Posso verificar o carimbo de data/hora sem depender do Timestamp GIT?
Sim. Os arquivos de recibo .ots e as provas de Merkle são independentes de fornecedor — SHA-256 mais dados de bloco do Bitcoin, sem formato proprietário. Você pode baixá-los e conferi-los contra a blockchain do Bitcoin com ferramentas padrão do OpenTimestamps, ou usar a página de verificação no navegador, que faz todos os cálculos localmente no seu navegador. Vale a pena ler sobre essa verificação local separadamente: veja Como Verificar uma Prova de Carimbo de Data/Hora Bitcoin no Seu Navegador.
E se meu repositório for privado ou contiver código sensível?
O Timestamp GIT nunca lê ou armazena seu código-fonte — apenas hashes de commit são processados. Para isolamento mais rígido, o modo Enterprise ZK tem uma GitHub Action que envia apenas hashes a partir da sua própria infraestrutura, ou você pode auto-hospedar com Docker. Se estiver avaliando os trade-offs em relação a outras abordagens, Alternativas ao Timestamp GIT: O Que Comparar Primeiro cobre as dimensões de comparação.
E se eu usar várias organizações do GitHub?
Instale o App em cada organização e monitore os repositórios de que precisa. Seu painel agrega todos os repositórios monitorados em um só lugar.
Conclusão
O valor de um carimbo de data/hora é inversamente proporcional à atenção que ele exige. Uma prova que você gera manualmente é uma prova que existe para os commits de que você se lembrou — o que, em uma auditoria, é lido como um processo inconsistente, e não como um processo protegido.
Instalar o GitHub App leva uma sessão de administrador. Depois disso, todo commit em um repositório monitorado é transformado em hash, agrupado, reduzido a uma raiz de Merkle e ancorado no Bitcoin enquanto você dorme, com badges para credibilidade pública, livros-razão CSV para conformidade e recibos .ots que sobrevivem a qualquer fornecedor. Os desenvolvedores não mudam nada.
Pronto para parar de fazer isso à mão? Instale o GitHub App na sua organização — gratuito para repositórios públicos, com planos Pro Agency e Enterprise ZK para repositórios privados e fluxos apenas com hashes.
Posts relacionados
- OpenTimestamps Sem a CLI: Carimbo de Data/Hora Bitcoin Gerenciado
- Como Verificar uma Prova de Carimbo de Data/Hora Bitcoin no Seu Navegador
- Como Carimbar Commits do Git Sem a Linha de Comando