Automatize o carimbo de data/hora em commits Git com um GitHub App

Se você já tentou provar quando um commit Git existiu, já conhece o trabalho manual: extrair hashes de commit, criar um manifesto, aguardar confirmações, armazenar arquivos de recibo em algum lugar seguro e repetir. É repetitivo, fácil de esquecer e desmorona no momento em que mais de um repositório ou membro da equipe está envolvido.

Existe uma maneira melhor de automatizar o carimbo de data/hora Bitcoin para commits git com um GitHub App. O Timestamp GIT transforma a prova de existência em um serviço em segundo plano: instale o GitHub App uma vez, conecte um repositório e todos os commits serão ancorados à blockchain do Bitcoin todas as noites. Você não precisa executar ferramentas de protocolo bruto, lembrar de cron jobs ou se tornar um especialista em blockchain. O fluxo de trabalho bruto do OpenTimestamps existe, mas fazê-lo manualmente é o caminho difícil.

Este artigo percorre o fluxo de trabalho de automação, a configuração única, o que acontece entre o commit e a âncora Bitcoin, e como monitorar e usar as provas resultantes.

O Trabalho Manual de Carimbo de Data/Hora Que Você Pode Eliminar

O processo manual para carimbar commits Git geralmente se parece com isto:

1. Esperar até lembrar que um commit deveria ter sido carimbado.
2. Extrair o hash do commit do Git.
3. Preparar um arquivo contendo os hashes que você deseja provar que existiam.
4. Executar uma ferramenta de carimbo de data/hora nesse arquivo.
5. Aguardar a prova ser criada e confirmada.
6. Armazenar o recibo em algum lugar durável.
7. Torcer para que ninguém peça para você explicar as etapas exatas mais tarde.

Esse fluxo de trabalho tem três problemas sérios.

Primeiro, os desenvolvedores esquecem de carimbar. A prova de existência só ajuda se o carimbo de data/hora foi criado antes da disputa. Se você lembrar três meses depois do fato, a evidência pode ser mais fraca do que poderia ter sido.

Segundo, as provas se perdem. Um arquivo de recibo salvo em um laptop, um disco de backup antigo ou um canal aleatório não é uma trilha de auditoria. Em um contexto jurídico ou de conformidade, recibos ausentes parecem evidências ausentes.

Terceiro, etapas manuais não escalam. Um desenvolvedor solo pode ocasionalmente carimbar um commit de release. Uma startup com 15 repositórios, múltiplos contribuidores e merges diários não pode depender de alguém exportando hashes manualmente todas as noites.

O Timestamp GIT automatiza todo o protocolo OpenTimestamps por trás de um serviço gerenciado. O produto não lê seu código-fonte. Ele coleta apenas hashes de commit, agrupa-os em lotes e cria provas criptográficas incorporadas à blockchain do Bitcoin. Você nunca toca em uma CLI, nunca constrói uma árvore Merkle e nunca supervisiona um processo de confirmação.

Configuração Única: Conecte Seu Repositório

O caminho de configuração foi projetado para ser feito uma vez e depois esquecido.

Você começa instalando o Timestamp GIT GitHub App e selecionando os repositórios que deseja monitorar. Repositórios públicos podem ser cobertos pelo plano Open Source gratuito. Repositórios privados estão disponíveis nos planos Pro Agency ou Enterprise ZK.

O Timestamp GIT oferece dois modos de implantação.

Modo Padrão

No Modo Padrão, o GitHub App monitora seu repositório por meio de webhooks do GitHub. Quando um novo commit aparece, o app lê apenas o hash do commit HEAD.

As permissões do GitHub exigem acesso somente leitura ao repositório de origem porque o GitHub não oferece um escopo de acesso apenas para hash de commit. O Timestamp GIT também precisa de acesso de leitura e gravação ao repositório de destino onde as provas serão gravadas. O branch de provas pode viver no mesmo repositório ou em um repositório sombra separado.

A parte importante: seu código-fonte nunca é lido, copiado ou armazenado. Apenas hashes de commit entram no pipeline do Timestamp GIT.

Modo Enterprise ZK

O Modo Enterprise ZK é para equipes que não podem conceder nenhum acesso de leitura ao repositório a terceiros. Em vez disso, um GitHub Action de 12 linhas é executado em sua própria infraestrutura e envia apenas o hash do commit para a API do Timestamp GIT.

Nesse modo, o Timestamp GIT precisa de acesso de leitura e gravação apenas ao repositório de destino onde as provas são armazenadas. Ele não precisa de acesso de leitura ao repositório de origem. Seu código-fonte nunca sai do seu ambiente.

Após a conexão inicial, não há etapas manuais. Cada commit em um repositório monitorado é captado automaticamente.

O Pipeline Automatizado: Do Commit à Âncora Bitcoin

Uma vez que um repositório está conectado, o pipeline de automação cuida do resto.

O pipeline funciona assim:

1. Detecção de commit
   O GitHub App detecta novos commits por meio de webhooks, ou seu GitHub Action envia hashes de commit para a API.

2. Fila de hashes
   Os hashes de commit são armazenados em um armazenamento chave-valor em memória para agrupamento em lotes.

3. Lote noturno
   Todas as noites, um worker agrupa hashes pendentes e cria um arquivo de manifesto .txt para cada repositório.

4. Árvore Merkle e OpenTimestamps
   O Timestamp GIT constrói uma árvore Merkle nativamente, cria provas OpenTimestamps usando calendários públicos e ancora a raiz Merkle na blockchain do Bitcoin.

5. Entrega da prova
   O manifesto e os arquivos de recibo .ots são enviados de volta para um branch de timestamps dedicado ou repositório sombra.

A confirmação do Bitcoin normalmente leva algumas horas, geralmente em torno de três horas. Isso significa que as provas geralmente estão disponíveis no dia seguinte após o lote noturno ser enviado.

Você pode verificar o status atual de um repositório por meio da API pública:

curl -s https://timestampgit.dev/api/statusLast/acme/widget-api

curl -s https://timestampgit.dev/api/statusCount/acme/widget-api

curl -s https://timestampgit.dev/api/statusSummary/acme/widget-api

Repositórios privados anexam um HMAC criptografado a essas URLs, para que apenas usuários autorizados possam ver o status. O HMAC é específico da instância do servidor Timestamp GIT.

A API também expõe endpoints de verificação e relatórios:

• GET /api/verify/{user}/{repo}/{date} retorna os dados completos da cadeia Merkle para verificação local de um dia específico.
• GET /api/audit/{user}/{repo} baixa o livro-razão de auditoria completo como CSV.
• GET /api/report/{user}/{repo}/{date} baixa um certificado PDF para uma data específica.

O endpoint de gerenciamento de repositórios, GET /api/repos/{user}, lista os repositórios monitorados após a instalação do GitHub App.

Para o Modo Enterprise ZK, o assistente de configuração fornece uma URL assinada. O GitHub Action envia apenas o identificador do commit para essa URL. O fluxo de trabalho é intencionalmente pequeno, sem necessidade de checkout do código-fonte além do payload de evento já disponível no GitHub Actions.

Monitoramento e Tratamento de Falhas

A automação deve ser observável. O Timestamp GIT fornece um painel de status público para cada repositório.

O painel inclui:

• Longevidade da prova
• Data de ancoragem mais antiga
• Regularidade diária
• Dados de bloco e transação Bitcoin
• Um mapa de calor de calendário
• CSV de auditoria para download
• Downloads de certificado PDF

Você também pode incorporar um selo de verificação no seu README. O endpoint autenticado GET /api/badgeLink/{user}/{repo} retorna URLs de selo e trechos Markdown prontos para uso para Shields.io. O selo exibe publicamente o status de verificação e vincula à página de verificação.

Se a confirmação do Bitcoin demorar mais do que o esperado, o painel de status mostra onde a prova está no processo. Como o sistema agrupa em lotes noturnos, uma confirmação lenta geralmente significa que a prova aparece algumas horas mais tarde do que o normal, em vez de desaparecer. Os hashes enfileirados permanecem no pipeline, e você pode verificar a página de status para o estado atual.

A garantia importante: sua prova não depende do Timestamp GIT permanecer disponível. Os arquivos .ots são armazenados no seu repositório, e a prova depende apenas de SHA-256 e dados de bloco do Bitcoin. Você pode verificá-la localmente mesmo que a empresa desapareça.

Melhores Práticas para Carimbo de Data/Hora Automatizado

A automação remove o fardo manual, mas alguns hábitos tornam a evidência mais forte.

Carimbe cada commit, não apenas releases.
Releases são marcos úteis, mas uma cadeia contínua de hashes de commit cria um registro muito mais rico. Se uma disputa for sobre um detalhe de implementação específico, um carimbo de data/hora em nível de release pode ser grosseiro demais.

Use um repositório sombra dedicado para provas.
Manter arquivos .ots e arquivos de manifesto em um repositório de provas separado mantém seu repositório principal limpo. Também facilita a coleta de auditoria porque todos os dados de prova vivem em um só lugar.

Considere auto-hospedagem Docker para ambientes isolados.
O Timestamp GIT está disponível como imagem Docker para equipes que precisam de controle máximo. A configuração de início rápido é:

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

O aplicativo está disponível em http://localhost:8080 após a inicialização. Um assistente de configuração orienta você na conexão do seu GitHub App e na configuração da instância. Uma licença de demonstração com tempo limitado está disponível na página de licença Docker.

Baixe relatórios de auditoria regularmente.
Trate o livro-razão de auditoria CSV e os certificados PDF como documentos legais. Armazene-os com seus outros registros de proteção de PI. Não espere uma disputa começar para coletar evidências.

Combine o carimbo de data/hora com outras estratégias de proteção de PI.
O carimbo de data/hora não substitui patentes, contratos ou políticas de segredo comercial. É a prova criptográfica que torna essas outras estratégias muito mais difíceis de contestar.

FAQ

O GitHub App precisa de acesso ao meu código-fonte?

Não. No Modo Padrão, o GitHub App lê apenas o hash do commit HEAD, não o código em si. No Modo Enterprise ZK, um GitHub Action na sua infraestrutura envia apenas o hash do commit para a API, então o código-fonte nunca sai do seu ambiente.

Quanto tempo leva para um commit ser carimbado?

Os commits são agrupados em lotes noturnos. O processo de ancoragem no Bitcoin normalmente leva algumas horas após o lote ser enviado, então as provas geralmente estão disponíveis no dia seguinte. Você pode verificar o painel de status para atualizações em tempo real.

Posso verificar o carimbo de data/hora sem depender do Timestamp GIT?

Sim. A prova é um arquivo OpenTimestamps .ots padrão que pode ser verificado independentemente usando ferramentas públicas e a blockchain do Bitcoin. O Timestamp GIT também fornece uma página de verificação baseada em navegador e certificados PDF para download.

O que acontece se o Timestamp GIT sair do mercado?

Suas provas permanecem válidas porque estão ancoradas na blockchain do Bitcoin e usam apenas padrões abertos como SHA-256 e OpenTimestamps. Você pode verificá-las offline a qualquer momento, e os arquivos .ots são armazenados no seu repositório.

Automatize a Prova, Mantenha o Controle

O carimbo de data/hora manual é fácil de vender internamente e difícil de sustentar na prática. O valor da prova de existência vem da consistência: cada commit, todos os dias, sem recibos ausentes.

O Timestamp GIT transforma isso em um processo em segundo plano. Instale o GitHub App uma vez, conecte seus repositórios e o pipeline noturno cuida de hashes de commit, árvores Merkle, provas OpenTimestamps, ancoragem no Bitcoin e entrega de provas. Você monitora os resultados por meio de um painel, selos, auditorias CSV e certificados PDF.

Repositórios públicos podem começar gratuitamente. Repositórios privados são cobertos pelos planos Pro Agency e Enterprise ZK. Se você precisa de controle isolado, a licença Docker auto-hospedada coloca a mesma automação dentro da sua própria infraestrutura.

Comece com o Timestamp GIT e torne a prova de existência uma parte normal do seu fluxo de trabalho de commits.

Posts relacionados

• Alternativa ao OpenTimestamps: Carimbo de Data/Hora Gerenciado para Git
• Proteção de Código para Freelancers: Uma Solução de Carimbo de Data/Hora
• Como o Bitcoin Pode Provar Que Sua PI Existiu Primeiro