Timestamp GIT

← Todos os artigos

2026-10-22

Timestamping Automatizado do Git: Ancore Commits ao Bitcoin

Timestamping Automatizado do Git: Ancore Commits ao Bitcoin
timestamp git blockchain proof

Carimbo de Tempo Automatizado no Git: Ancorando Commits ao Bitcoin

Se a sua proteção de anterioridade depende de alguém se lembrar de executar uma ferramenta após cada commit, você não tem proteção de anterioridade — você tem um hábito. E hábitos quebram na semana anterior a uma auditoria, durante um pico de release, ou logo depois que a pessoa que “sempre fazia isso” muda de equipe.

O carimbo de tempo manual tem um ciclo de falha previsível. Você faz o commit, depois se lembra de carimbar. Você copia o recibo para algum lugar onde ele não vai se perder. Você faz isso de novo amanhã, e depois de amanhã, para todo repositório que importa — e no momento em que você entra em um sprint com muitas branches, o ciclo para silenciosamente. Um repositório escala. Cinco repositórios com três contribuidores cada, não.

Este artigo é sobre eliminar esse ciclo por completo: carimbo de tempo automatizado no Git sobre Bitcoin, onde a única ação recorrente é um commit que você já ia fazer de qualquer forma.

Você pode fazer isso do jeito difícil, executando as ferramentas do OpenTimestamps por conta própria e cuidando dos arquivos de recibo. O Timestamp GIT existe para que você não precise. É um serviço gerenciado que esconde o protocolo por completo: instale o GitHub App uma vez, e todo commit em um repositório monitorado é ancorado no Bitcoin automaticamente todas as noites. Sem ferramentas de CLI, sem comandos de protocolo, sem checklist diário. Para o passo a passo da instalação em si, veja Configuração de Carimbo de Tempo Blockchain via GitHub App: Instale Uma Vez, Carimbe Para Sempre — este artigo foca no que acontece depois da instalação.

A Tarefa Manual Repetitiva Que Você Pode Eliminar

Antes de optar pela automação, vale nomear exatamente o que está sendo removido da sua semana:

  • Um ritual por commit. Algo precisa rodar após cada commit que merece prova. Isso é um humano no loop, em cada commit, para sempre.
  • Recibos espalhados. Arquivos de prova acabam em uma pasta pessoal, um drive compartilhado ou uma thread do Slack. Seis meses depois, ninguém consegue mapear um recibo para uma data ou um repositório.
  • Deterioração da cobertura. Você protege o repositório principal. O repositório de ferramentas internas, a biblioteca de cliente, o serviço de segredo comercial — ninguém carimba esses, e frequentemente são justamente os que importam em uma disputa.
  • Lacunas silenciosas. Perder um único dia é invisível até você precisar da prova, que é o pior momento possível para descobrir um buraco na sua linha do tempo.

O que “automatizado” significa aqui é restrito e específico. Você instala o GitHub App uma vez nos repositórios que deseja monitorar. A partir daí, todo commit é detectado, agrupado e ancorado na blockchain do Bitcoin todas as noites com nenhuma ação do desenvolvedor. Os desenvolvedores continuam fazendo commits exatamente como fazem hoje. Não há nada para instalar nas máquinas deles, nenhum hook de pré-commit, nenhum novo fluxo de trabalho para aprender.

Essa é a diferença entre um processo e uma propriedade de fundo dos seus repositórios.

Configuração Única: Instale o GitHub App e Esqueça

O Timestamp GIT oferece duas formas de conectar um repositório, ambas configurações únicas.

Modo Padrão (GitHub App). Instale o GitHub App nos repositórios que deseja monitorar. Ele lê automaticamente apenas o hash do commit HEAD de cada repositório monitorado. As provas são gravadas em uma branch Git dedicada — seja no mesmo repositório da origem ou em um separado.

Vale entender o modelo de permissões de forma clara, porque é menos do que as pessoas esperam:

  • Acesso somente leitura ao repositório de origem. O sistema de permissões do GitHub não tem um escopo “apenas hash de commit”, então somente leitura é o mínimo que o App pode solicitar para ver o hash HEAD.
  • Acesso leitura-escrita ao repositório de destino, que é onde os arquivos de manifesto e recibo são enviados.

Modo Enterprise ZK. Uma GitHub Action de 12 linhas roda na sua própria infraestrutura e envia apenas o hash do commit para a API do Timestamp GIT. Essa configuração exige acesso leitura-escrita apenas ao repositório de destino — nenhum acesso de leitura ao repositório de origem é necessário, e sua origem nunca sai do seu ambiente.

Qualquer que seja o modo escolhido, a experiência do desenvolvedor é idêntica para sua equipe: nada para instalar nas máquinas dos desenvolvedores, nenhuma mudança em como qualquer pessoa cria branches, faz commits ou faz merges.

Se você precisar hospedar por conta própria. Para segurança máxima ou ambientes isolados (air-gapped), o Timestamp GIT também está disponível como imagem Docker. 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
docker compose pull
docker compose up -d
docker compose logs -f timestampgit

A aplicação fica disponível em http://localhost:8080 após a inicialização, e um assistente de configuração guia você na conexão do seu GitHub App e na configuração da sua instância no primeiro lançamento. Licenciamento, o formulário de solicitação de licença de demonstração e o passo a passo completo de auto-hospedagem estão em Carimbos de Tempo Git Auto-Hospedados: Guia de Configuração Docker e Licença.

O Pipeline Automatizado: Do Commit à Âncora no Bitcoin

Uma vez conectado, o pipeline roda sem você. Aqui está a sequência real.

1. Detecção de commit. Ou o GitHub App detecta novos commits via webhooks, ou — no Modo Enterprise ZK — sua GitHub Action envia hashes de commit para a API.

2. Fila de hashes. Os hashes de commit chegam a um armazenamento chave-valor em memória para agrupamento. Nada mais é armazenado, porque nada mais foi enviado.

3. O worker cron da meia-noite. Todas as noites, um worker:

  • Agrupa todos os hashes pendentes
  • Cria arquivos de manifesto por repositório (.txt)
  • Constrói uma árvore de Merkle nativamente
  • Cria provas OpenTimestamps usando calendários OTS públicos
  • Ancora a raiz de Merkle na blockchain do Bitcoin

4. Entrega da prova. Os arquivos de manifesto e recibo .ots são enviados de volta ao seu repositório em uma branch de carimbos de tempo dedicada ou repositório sombra.

Todo o fluxo se parece com isto:

commit ──▶ hash queue ──▶ midnight cron ──▶ Merkle root ──▶ Bitcoin block
                                                 │
                                                 └──▶ manifest.txt + .ots receipt
                                                              │
                                                              ▼
                                                  timestamps branch / shadow repo

No Modo Enterprise ZK, sua GitHub Action conversa com a API ZK Commit, que é autenticada com um HMAC da URL assinada que a API retorna para o seu repositório:

# The signed URL (and its HMAC) is returned by the API for your repo.
# {target} is the destination repo, {hash} is the HMAC from that URL.
curl -X POST \
  "https://timestampgit.dev/api/timestamp/acme/payments-api/timestamps/<hmac>/<commitHash>/<commitId>"

Expectativa de tempo. A confirmação do Bitcoin leva várias horas — normalmente cerca de 3 — então a gravação da prova é concluída algumas horas após a execução noturna, não à meia-noite em ponto. Se você verificar sua branch de carimbos de tempo às 00:05 e não vir nada, isso é comportamento esperado, não uma falha.

Monitoramento e Tratamento de Falhas

Automação que você não consegue observar é indistinguível de automação que parou de funcionar. O Timestamp GIT expõe endpoints públicos de status para que você possa acompanhar o pipeline sem fazer login:

# Last anchored Bitcoin block
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api

# Total committed / stamped commit count
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api

# Combined summary (Shields.io friendly)
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api

Badges. Badges de verificação incorporáveis estão disponíveis para o seu README, para que o status da âncora fique visível a qualquer pessoa que navegue pelo repositório. Qualquer um pode seguir o link do badge para verificar o carimbo de tempo — há um visualizador dedicado e um relatório em PDF. Repositórios privados também são suportados: suas URLs de status acrescentam um HMAC criptografado específico da instância do servidor, então apenas usuários autorizados podem ver o status.

Painel de Status do Repositório. Em /status/{user}/{repo} você obtém longevidade das provas, data da âncora mais antiga, regularidade diária, dados de bloco e transação do Bitcoin, e um mapa de calor em calendário — a forma mais rápida de identificar visualmente uma lacuna na cobertura.

Endpoints de auditoria e relatórios. Quando você precisa de evidência em vez de um painel:

# Full audit ledger as CSV
curl -sO https://timestampgit.dev/api/audit/acme/payments-api

# PDF certificate for one specific date
curl -sO https://timestampgit.dev/api/report/acme/payments-api/2026-10-21

Quando uma noite parecer faltando, siga esta ordem:

  1. Verifique statusLast e statusCount. Se a última âncora for várias horas mais antiga do que o esperado, a confirmação pode simplesmente ainda estar em andamento.
  2. Confirme que o GitHub App ainda tem acesso ao repositório. Um App desinstalado, uma permissão revogada ou um repositório renomeado interromperão a detecção silenciosamente.
  3. No Modo Enterprise ZK, verifique o histórico de execuções da Action do seu lado — o envio para a API é o único elo que pode se romper localmente.
  4. Verifique novamente após a confirmação do Bitcoin ser concluída antes de presumir que algo se perdeu.

Boas Práticas para Carimbo de Tempo Automatizado

  • Monitore todo repositório que importa, não apenas o principal. A cobertura é todo o valor da automação; um único repositório protegido ainda deixa o resto do seu trabalho exposto.
  • Mantenha commits significativos. A automação carimba o que você faz commit, então a higiene de commits ainda molda a história que seu histórico ancorado conta. Cem commits “wip” provam menos do que um histórico limpo e descritivo.
  • Coloque o badge no README e guarde o CSV de auditoria e os relatórios PDF por data junto aos seus registros de PI. Esses artefatos são o que você entrega a um auditor ou à parte adversa.
  • Verifique de forma independente quando for importante. Baixe o arquivo .ots e confira-o com ferramentas padrão do OpenTimestamps contra o Bitcoin. A prova é independente de fornecedor por design — usa apenas SHA-256 e dados de blocos do Bitcoin. O passo a passo está em Como Verificar uma Prova de Carimbo de Tempo Bitcoin Localmente.
  • Lembre-se da garantia de conhecimento zero. Apenas hashes de commit são carimbados, nunca código-fonte, então automatizar em todos os repositórios não amplia sua exposição em nada — é o mesmo hash quer você tenha um repositório ou cinquenta.

FAQ

O carimbo de tempo automatizado no Git chega a ler ou armazenar meu código-fonte?

Não. O Timestamp GIT processa apenas hashes de commit. No Modo Padrão, o GitHub App lê o hash do commit HEAD, e no Modo Enterprise ZK uma GitHub Action na sua infraestrutura envia apenas o hash para a API. Seu código-fonte nunca sai do seu ambiente no modo ZK e nunca é copiado ou armazenado pelo serviço.

Quanto tempo após o commit a âncora no Bitcoin é confirmada?

Os commits são agrupados e ancorados por um worker cron noturno. A confirmação do Bitcoin leva várias horas, normalmente cerca de 3 horas, então os arquivos de recibo .ots e de manifesto aparecem na sua branch de carimbos de tempo ou repositório sombra algumas horas após a execução noturna.

O que acontece com minhas provas se o Timestamp GIT encerrar as atividades?

As provas permanecem válidas. Elas dependem apenas de SHA-256 e dados de blocos do Bitcoin via protocolo OpenTimestamps, então qualquer pessoa pode baixar o arquivo .ots e verificá-lo de forma independente contra a blockchain do Bitcoin usando ferramentas padrão do OpenTimestamps — sem tecnologia proprietária, sem aprisionamento tecnológico.

Posso usar carimbo de tempo automatizado com repositórios privados?

Sim. Repositórios privados são suportados, e as URLs de status acrescentam um HMAC criptografado específico da instância do servidor, então apenas usuários autorizados podem ver o status. Badges de verificação públicos e o painel de status funcionam da mesma forma assim que o acesso é concedido.

Conclusão: Configure Uma Vez, Prove Para Sempre

A mudança aqui é pequena em esforço e grande em consequência. Você para de manter uma tarefa diária e passa a ter uma propriedade dos seus repositórios: todo commit, ancorado no Bitcoin, automaticamente, todas as noites, com um recibo que você pode entregar a um advogado, um auditor ou um tribunal. A prova está embutida no Bitcoin, pronta para tribunal e verificável por qualquer pessoa sem ferramentas proprietárias — e tudo é conduzido pelo Timestamp GIT no backend, não pelos seus desenvolvedores.

Se sua equipe não puder usar um serviço gerenciado de forma alguma, a opção Docker auto-hospedada cobre ambientes de segurança máxima e isolados (air-gapped) com a configuração Compose mostrada acima.

Instale o GitHub App no seu primeiro repositório hoje e deixe o pipeline rodar esta noite. Amanhã, verifique statusLast — você terá uma âncora que, de outra forma, teria passado um ano tentando lembrar de criar.

Posts relacionados

EU label: AI-generated content