Timestamp GIT

← Todos os artigos

2026-11-15

Carimbo automático de data e hora em commits Git sem CLI

Carimbo automático de data e hora em commits Git sem CLI
timestamp git blockchain proof

Carimbo de Tempo Automático em Commits Git Sem Nenhuma CLI

A maioria das equipes que deseja prior art criptográfico nunca o obtém, e o motivo quase nunca é técnico. É operacional. Um hábito de carimbo de tempo só funciona se uma pessoa lembrar de executar a ferramenta no commit certo, no momento certo, e armazenar o recibo em algum lugar onde o auditor o encontre dezoito meses depois. Sob pressão de prazos, esse hábito é o primeiro a morrer.

Este artigo trata de eliminar o hábito por completo. Não “como executar um comando de carimbo de tempo com mais frequência”, mas como fazer com que cada commit em um repositório monitorado seja ancorado automaticamente na blockchain do Bitcoin, toda noite, sem nenhum comando digitado por ninguém da sua equipe. Se você está avaliando se vale a pena aprender o protocolo bruto em vez de usar um GitHub App gerenciado, cobrimos esse trade-off separadamente em OpenTimestamps vs Timestamp GIT: Manual Proofs or GitHub App?. Aqui assumimos que você já decidiu que quer a automação.

A Armadilha do Carimbo de Tempo Manual (E Por Que Você Quer Sair Dela)

Imagine como o carimbo de tempo manual realmente acontece:

  1. Alguém termina uma branch de feature e lembra — geralmente depois do fato — que esse commit deveria receber carimbo de tempo.
  2. A pessoa executa uma ferramenta, espera e recebe um arquivo de recibo de volta.
  3. O recibo é renomeado, jogado em uma pasta proofs/, commitado ou, pior, enviado por e-mail para um gerente.
  4. Ninguém faz isso nos próximos quarenta commits porque a sprint ficou corrida.

A CLI bruta do OpenTimestamps existe e é o jeito difícil de fazer isso: é um caminho voltado a especialistas, no qual você é responsável pelo batching, pelos arquivos de prova, pela interação com o calendário e pelo sistema de arquivamento. Funciona. Também depende de uma pessoa ser disciplinada para sempre, e não deixa trilha de auditoria explicando por que o commit 4f9c1ab tem uma prova e o commit 8d2e0f3 não tem.

O modo de falha de conformidade é pior do que o inconveniente. Um registro de prior art com buracos é um registro que um advogado pode desmontar. Se uma contraparte pede “prove como seu código estava no dia 14 de março”, e sua resposta é uma planilha mais a memória de um desenvolvedor, você já perdeu o enquadramento. Processos manuais também são difíceis de auditar: não há artefato consistente, nem cadência regular, nem forma de um revisor de conformidade confirmar a cobertura sem pedir que os engenheiros reconstruam o próprio histórico.

A promessa da automação é diferente em natureza, não em grau: instale uma vez e, a partir daquele momento, cada commit em um repositório monitorado é fingerprintado e ancorado todas as noites. Nenhuma CLI para aprender, nenhum recibo para arquivar à mão, nada instalado nas máquinas dos desenvolvedores. O registro de provas passa a ser uma propriedade do repositório, e não uma propriedade da diligência de alguém.

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

O caminho principal é o GitHub App. Você o instala em um repositório ou na organização inteira, e a configuração é genuinamente única — sem scripts por repositório, sem etapa de onboarding de desenvolvedores.

Modo Standard (GitHub App). O App lê automaticamente o hash do commit HEAD de cada repositório monitorado. O modelo de permissões do GitHub não oferece um escopo de “apenas hash de commit”, então o App exige pelo menos acesso somente leitura ao repositório de origem. Também precisa de acesso leitura-escrita ao repositório de destino, porque é lá que as provas são gravadas: uma branch dedicada de timestamps, seja no mesmo repositório da origem ou em um repositório shadow separado.

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. Nesse modo, o serviço não precisa de nenhum acesso de leitura ao repositório de origem — apenas acesso leitura-escrita ao repositório de destino para entrega das provas — e você instala a Action no seu workflow. Escolha este modo quando o acesso de leitura ao código-fonte for inviável por motivos de política, ou quando sua revisão de segurança exigir que os hashes se originem dentro do seu perímetro. Escolha o modo Standard quando quiser o mínimo absoluto de peças móveis.

Standard (GitHub App) Enterprise ZK (GitHub Action)
Acesso ao repositório de origem Somente leitura Nenhum
Acesso ao repositório de destino Leitura-escrita Leitura-escrita
Onde os hashes se originam O App Seu runner de CI
Esforço de configuração Instalar o App Instalar o App + adicionar a Action

Em ambos os modos, nada é instalado nas máquinas dos desenvolvedores. Os engenheiros continuam commitando exatamente como fazem hoje, e todo o pipeline roda no lado do servidor. O serviço nunca vê, copia ou armazena seu código-fonte — ele lida apenas com hashes de commit.

Se você precisa rodar tudo dentro da sua própria rede, o Timestamp GIT também está disponível como imagem Docker 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
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 de primeiro lançamento orienta você na conexão do seu GitHub App e na configuração da instância. Uma licença de demonstração por tempo limitado para avaliação pode ser solicitada na página Docker License. Aprofundamos a implantação em Self-Host Git Timestamping With Docker Compose.

O Pipeline Automatizado: Do Commit à Ancoragem no Bitcoin

Depois que o App está instalado, eis o que acontece sem você:

  1. Detecção de commits. O GitHub App captura novos commits via webhooks, ou sua GitHub Action envia hashes de commit para a API. Apenas hashes trafegam.
  2. Fila de hashes. Os hashes de commit chegam a um armazenamento chave-valor em memória, aguardando o lote noturno.
  3. Worker cron da meia-noite. A cada noite, um worker agrupa todos os hashes pendentes, grava um arquivo de manifesto de texto por repositório, constrói uma árvore de Merkle nativamente, cria provas OpenTimestamps usando 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 — uma branch dedicada de timestamps ou um repositório shadow — para que as provas fiquem ao lado do código que descrevem.

Uma observação prática sobre o timing: a confirmação do Bitcoin leva várias horas, normalmente cerca de três. Então um commit feito na terça-feira termina com uma prova finalizada na manhã de quarta-feira, não na noite de terça. Esse é o custo de ancorar em um ledger público e imutável, e é um custo que vale a pena pagar.

Você não precisa aceitar nada disso pela fé. Todo repositório monitorado ganha um dashboard de status público mostrando a longevidade das provas, a data de ancoragem mais antiga, a regularidade diária, os dados de bloco e transação do Bitcoin por trás de cada ancoragem e um heatmap de calendário que você pode inspecionar visualmente em busca de lacunas. A mesma página oferece certificados CSV e PDF de auditoria para download. A verificação em si acontece em /verification/{user}/{repo}/{date}, que percorre a cadeia de Merkle multinível passo a passo — e toda essa computação acontece localmente no navegador, então ninguém vê o que você verifica.

Para READMEs, badges incorporáveis exibem publicamente o status de verificação, e qualquer pessoa pode seguir o link do badge para verificar o carimbo de tempo no site ou baixar o relatório em PDF.

Para integrar o status aos seus próprios dashboards, a API pública é deliberadamente simples:

# Last anchored Bitcoin block info
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 (what the Shields.io badge consumes)
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api

E quando a conformidade pedir artefatos, não fique clicando em uma interface às 17h de uma sexta-feira:

# Full audit ledger as CSV
curl -sL -o audit-acme-payments-api.csv \
  https://timestampgit.dev/api/audit/acme/payments-api

# PDF certificate for a specific day
curl -sL -o certificate-2026-11-14.pdf \
  https://timestampgit.dev/api/report/acme/payments-api/2026-11-14

URLs de badge e markdown pronto para colar vêm de /api/badgeLink/{user}/{repo} (autenticado). Para repositórios privados, as URLs de status carregam um HMAC criptografado específico da sua instância de servidor, então apenas usuários autorizados podem lê-las.

Monitoramento e Tratamento de Falhas: Mantendo a Automação Honesta

Automação que você não observa é automação que você não sabe se está funcionando. Vale a pena criar hábito em torno de três coisas.

Observe lacunas, não erros. Se uma execução noturna falha, o sistema tenta novamente, e os hashes pendentes permanecem na fila em memória em vez de serem descartados. Mas a profundidade da fila e as retentativas são internas; o heatmap de calendário na página de status é o que você consegue realmente ler. Um dia faltante é visível imediatamente como um buraco na grade.

Faça polling e alerte. Um pequeno job agendado que compara o payload de status mais recente com o snapshot de ontem vai detectar um pipeline travado antes que um auditor o faça:

import json, pathlib, requests

REPO = "acme/payments-api"
URL = f"https://timestampgit.dev/api/statusSummary/{REPO}"
snapshot = pathlib.Path("last-status.json")

r = requests.get(URL, timeout=30)
r.raise_for_status()
current = r.json()

previous = json.loads(snapshot.read_text()) if snapshot.exists() else None

if previous == current:
    print("WARNING: status unchanged since last poll - check the repo status page")
else:
    print("new anchor data:", json.dumps(current))

snapshot.write_text(json.dumps(current, indent=2))

Rode-o a cada hora no CI, ou diariamente logo após a janela do cron, e encaminhe o alerta para algum lugar onde humanos olhem.

Planeje auditorias em torno do atraso de confirmação. Como a ancoragem no Bitcoin leva algumas horas após a execução do worker cron, “carimbe tudo do release de ontem à noite, preciso do certificado em dez minutos” não é um pedido que alguém consiga atender. Dê à conformidade uma regra simples: as provas do dia N estão finalizadas no dia N+1.

A parte tranquilizadora do tratamento de falhas é o que acontece se o serviço estiver totalmente indisponível. A verificação não depende de nós. O arquivo de recibo .ots pode ser verificado offline contra a blockchain do Bitcoin usando ferramentas padrão de verificação do OpenTimestamps, porque a prova depende apenas de SHA-256 e dos dados de bloco do Bitcoin — nenhuma tecnologia proprietária, nenhum lock-in. Mesmo que o fornecedor desapareça, a prova permanece.

Boas Práticas para Carimbo de Tempo sem Intervenção

  • Commite cedo e com frequência. Cada commit recebe fingerprint automaticamente, então um histórico denso de commits produz um registro denso de prior art. Fazer squash de um mês de trabalho em um único commit na noite anterior a um pedido de patente dá a você uma ancoragem em vez de duzentas.
  • Escolha o modo que corresponde à sua postura de segurança. Se o acesso de leitura ao repositório de origem estiver fora de cogitação, use o modo Enterprise ZK: apenas hashes de commit saem da sua infraestrutura, enviados pela GitHub Action.
  • Exporte ledgers de auditoria e certificados em uma agenda. Os arquivos de conformidade não devem depender de alguém lembrar de um link de download. Acesse /api/audit/{user}/{repo} mensalmente e /api/report/{user}/{repo}/{date} para datas marco, e armazene os resultados onde seus artefatos legais ficam.
  • Coloque o badge no seu README. Além do sinal que envia aos clientes, um badge de verificação ao vivo é um dissuasor barato contra alegações de “desenvolvemos isso de forma independente”.
  • Mantenha as provas em sua própria branch ou repositório shadow. Commits diários de provas em uma branch dedicada de timestamps mantêm seu histórico principal legível e mantêm a evidência anexada ao mesmo repositório.
  • Documente o processo. Para um auditor, documente quem instalou o GitHub App, quais repositórios são monitorados e onde fica a branch de timestamps. A matemática é verificável; a cadeia de custódia ainda precisa de um parágrafo.

FAQ

Preciso instalar algum software nas máquinas dos desenvolvedores?

Não. O Timestamp GIT é um serviço gerenciado que roda inteiramente no lado do servidor via GitHub App. Os desenvolvedores apenas commitam como de costume; nenhuma ferramenta de CLI ou instalação local é necessária.

Quanto tempo leva para um commit receber carimbo de tempo?

Os commits são agrupados em lotes noturnos e ancorados no Bitcoin. A confirmação do Bitcoin normalmente leva cerca de 3 horas, então as provas geralmente ficam disponíveis algumas horas após a execução do cron noturno.

Posso verificar as provas sem o serviço?

Sim. Você recebe um arquivo de recibo .ots imutável que pode ser verificado offline usando ferramentas padrão do OpenTimestamps contra a blockchain do Bitcoin. A prova é independente do fornecedor e depende apenas de SHA-256 e dos dados de bloco do Bitcoin.

E se eu usar um repositório privado?

O GitHub App funciona com repositórios privados. As URLs de status para repositórios privados incluem um HMAC criptografado específico da sua instância de servidor, então apenas usuários autorizados podem visualizar o status.

Conclusão

Todo o valor de um registro de prior art está em ele existir quando você precisar, o que significa que não pode depender de um humano lembrar de um comando. Instale o GitHub App uma vez, e cada commit nos repositórios monitorados é enfileirado, agrupado à meia-noite, enraizado em Merkle e ancorado no Bitcoin — com provas enviadas de volta para uma branch que você possui, um dashboard de status que você pode consultar e exportações CSV e PDF para os auditores.

Se o motivo de você não ter carimbado seu código era que isso sempre pareceu uma tarefa chata, esse motivo acabou de desaparecer. Comece em timestampgit.dev — conecte um repositório, deixe o primeiro lote noturno rodar e olhe o heatmap de calendário na manhã seguinte.

Posts relacionados

EU label: AI-generated content