Carimbar Automaticamente Commits do Git com um GitHub App

Você já sabe que provar quando um commit existiu pode ser tão importante quanto o próprio código. Se trolls de patentes, disputas com clientes ou um ex-colaborador questionarem sua linha do tempo, um log do Git auto-hospedado geralmente não é suficiente. Logs internos podem ser editados, e o histórico de um repositório hospedado não é uma prova imutável de estado da técnica.

O caminho difícil é aprender o protocolo de carimbo de tempo subjacente, executar comandos manuais para cada commit, copiar hashes, aguardar confirmações e armazenar recibos em algum lugar seguro. Essa abordagem quebra no momento em que você tem múltiplos repositórios, múltiplos desenvolvedores ou uma semana agitada de releases.

O Timestamp GIT elimina todo esse fardo manual. Você instala um GitHub App uma vez, seleciona os repositórios que deseja proteger, e cada novo commit é automaticamente carimbado na blockchain do Bitcoin em uma programação noturna. Não há ferramentas de CLI para executar, nenhum arquivo de recibo para gerenciar manualmente e nenhum comando OpenTimestamps para aprender.

Se você é novo na razão subjacente pela qual isso importa, veja O Que É Estado da Técnica Criptográfico e Por Que Isso Importa para Software?.

Este artigo percorre o caminho automatizado: configuração única, o que acontece entre o commit e a âncora no Bitcoin, como monitorar suas provas e como manter o processo saudável ao longo do tempo.

Configuração Única: Instale o GitHub App

Toda a configuração é uma instalação de GitHub App. Não há agente local, nenhum arquivo de configuração e nenhum script para manter.

Aqui está a sequência:

1. Instale o Timestamp GIT GitHub App do GitHub Marketplace.
2. Selecione os repositórios que deseja monitorar.
   • Repositórios públicos são suportados no plano gratuito.
   • Repositórios privados exigem o plano Pro ou Enterprise.
3. Escolha seu modo de implantação:
   • Modo Standard: O GitHub App lê o hash do commit HEAD do repositório de origem e grava os arquivos de prova em um repositório ou branch de destino.
   • Modo Enterprise ZK: Um GitHub Action executado no seu ambiente envia apenas os hashes dos commits para a API do Timestamp GIT. O Timestamp GIT recebe zero acesso de leitura ao repositório de origem.
4. Confirme o acesso.
   • O Modo Standard requer acesso de leitura ao repositório de origem e acesso de leitura-escrita ao repositório de destino. Esta é uma exigência do sistema de permissões do GitHub: não existe permissão de leitura apenas de hash de commit.
   • O Modo Enterprise ZK requer apenas acesso de leitura-escrita ao repositório de destino. O repositório de origem nunca precisa conceder acesso de leitura ao Timestamp GIT.
5. Pronto. A partir deste ponto, novos commits são detectados automaticamente.

Após a instalação, você pode gerenciar os repositórios monitorados pelo painel do Timestamp GIT. Não há nada para compilar, nenhum daemon para executar e nenhum cron job para configurar.

O Pipeline Automatizado: Do Commit à Âncora no Bitcoin

Uma vez que o GitHub App está instalado, o processo executa sem que você precise pensar nele.

O que acontece após cada commit

Quando você faz push de um commit para um repositório monitorado, o GitHub App detecta o novo commit via webhook. O app não lê seus arquivos de origem. Ele extrai apenas o hash do commit — uma impressão digital criptograficamente segura do estado do repositório naquele momento.

Esse hash de commit é colocado em uma fila para o próximo lote noturno.

A execução noturna de ancoragem

Cada noite, um processo worker executa o seguinte pipeline:

1. Todos os hashes de commit enfileirados de cada repositório monitorado são coletados.
2. Arquivos de manifesto são criados para o dia.
3. Uma árvore de Merkle é construída a partir dos hashes coletados.
4. A raiz de Merkle é ancorada na blockchain do Bitcoin usando o protocolo OpenTimestamps.
5. Os recibos de prova são gerados e enviados de volta para um branch dedicado de timestamps ou repositório sombra.

A confirmação do Bitcoin em si geralmente leva algumas horas. Isso significa que os arquivos de prova normalmente aparecem no seu repositório algumas horas após a execução noturna, não imediatamente após o commit.

Entrega da prova

O entregável é um arquivo de recibo .ots mais o manifesto diário. Esses arquivos são gravados em um branch dedicado ou repositório sombra, mantendo-os separados do seu histórico de código-fonte normal.

Você pode verificar o resultado com comandos Git comuns:

# Após a ancoragem noturna ter sido concluída
git fetch origin

# Procure pelo branch dedicado de timestamps ou repositório sombra
git branch -r

# Faça checkout do branch que contém os recibos .ots
git checkout <timestamps-branch>

# Liste os arquivos de prova diários
ls -1 *.ots

O nome exato do branch depende da configuração do seu repositório.

Modo Enterprise ZK

Para equipes que não podem conceder qualquer acesso ao código-fonte a terceiros, o Modo Enterprise ZK altera o fluxo de dados.

Em vez do GitHub App ler metadados do repositório de origem, um pequeno GitHub Action executa dentro da sua infraestrutura. A action envia apenas o hash do commit para a API do Timestamp GIT. O Timestamp GIT nunca recebe código, nunca lê o repositório de origem e nunca vê nada além do hash.

O pipeline de ancoragem noturna é o mesmo a partir desse ponto: fila de hashes, manifesto, árvore de Merkle, prova OpenTimestamps, âncora no Bitcoin e entrega da prova de volta ao seu repositório de destino.

Monitoramento e Tratamento de Falhas

Automação não significa confiança cega. Você deve ser capaz de ver que o sistema está funcionando, e deve ter um caminho claro quando algo parecer errado.

Painel de status do repositório

Cada repositório monitorado tem uma página de status que mostra:

• Longevidade da prova, incluindo a data de ancoragem mais antiga.
• Regularidade da ancoragem diária.
• Dados de bloco e transação do Bitcoin vinculados a cada carimbo de tempo.
• Um mapa de calor em calendário dos dias ancorados.
• Relatórios de auditoria CSV e certificado PDF para download.

Você também pode consultar o status através da API pública:

curl -s https://timestampgit.dev/api/statusLast/$GITHUB_USER/$GITHUB_REPO | jq .

Repositórios privados anexam um HMAC criptografado às URLs de status. Apenas usuários autorizados podem visualizar os timestamps de repositórios privados, e o HMAC é específico para a instância do servidor.

Badges no README

O Timestamp GIT fornece badges incorporáveis para o seu README. O badge mostra o estado de verificação atual, e qualquer pessoa que clicar pode verificar o timestamp a partir da página vinculada. Isso é útil para projetos de código aberto e para agências que desejam mostrar prova de trabalho publicamente sem expor código privado.

Exportações de auditoria e conformidade

Para conformidade ou revisão legal, você pode baixar:

• Um livro-razão de auditoria completo como CSV.
• Um certificado PDF para uma data específica.

Esses arquivos fornecem um registro off-chain que complementa os recibos criptográficos no seu repositório.

E se um commit for perdido?

Se um commit não for processado no lote noturno esperado, o hash enfileirado permanece na fila de carimbo de tempo e é capturado na próxima execução. O painel de status do repositório é o primeiro lugar para verificar lacunas ou irregularidades. Se um repositório mostrar consistentemente dias ausentes, entre em contato com o suporte antes de confiar no intervalo afetado para uma reivindicação legal.

Opção Docker auto-hospedada

Para ambientes air-gapped ou máximo controle operacional, o Timestamp GIT está disponível como imagem Docker. Uma instância auto-hospedada usa o mesmo fluxo de trabalho do GitHub App, mas executa em infraestrutura que você possui.

Uma configuração mínima 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

Inicie com:

docker compose pull
docker compose up -d
docker compose logs -f timestampgit

A aplicação está disponível em http://localhost:8080 após a inicialização. No primeiro lançamento, um assistente de configuração o guia pela conexão do seu GitHub App e configuração da instância. Uma licença demo limitada por tempo está disponível para avaliação.

Boas Práticas para Carimbo de Tempo Automatizado

A automação remove o trabalho repetitivo, mas alguns hábitos tornam seu histórico de timestamps muito mais forte.

Faça commits com frequência. O pipeline ancora lotes diários. Se você só faz commit uma vez por mês, cria menos pontos de prova e lacunas maiores entre as âncoras. Commits regulares criam um registro denso e contínuo de estado da técnica.

Use mensagens de commit significativas. Os hashes dos commits são o que é carimbado, mas a trilha de auditoria legível por humanos ainda importa. Uma mensagem como Implementar aquecimento de cache para respostas da API é muito mais útil em uma disputa do que corrigir coisas.

Mantenha os recibos .ots separados do código-fonte. Trate o branch de timestamps ou repositório sombra como um armazenamento de evidências somente de acréscimo. Evite editar, fazer squash ou excluí-lo.

Verifique uma amostra regularmente. Pelo menos uma vez por trimestre, abra a página de verificação pública para um timestamp representativo e confirme que a prova de Merkle resolve corretamente. Isso detecta desvios de configuração antes que você precise da evidência.

Use o Modo Enterprise ZK para projetos sensíveis. Se o repositório contém segredos comerciais, ferramentas internas ou lógica de produto não lançada, o Modo Enterprise ZK é o padrão mais forte. O Timestamp GIT só vê hashes de commit, e seu código nunca sai do seu ambiente.

Considere auto-hospedagem com Docker para ambientes regulados. Se você precisa de operação air-gapped ou controle total sobre a conexão do GitHub App, auto-hospede com a imagem Docker.

FAQ

Como funciona o carimbo de tempo automático com um GitHub App?

Uma vez que você instala o Timestamp GIT GitHub App e seleciona repositórios, o app detecta automaticamente novos commits via webhooks. Toda noite, ele agrupa todos os hashes de commit, cria uma árvore de Merkle e ancora a raiz na blockchain do Bitcoin usando OpenTimestamps. Os recibos de prova (arquivos .ots) são então enviados de volta para um branch dedicado no seu repositório — sem etapas manuais necessárias.

Meu código-fonte é exposto ao Timestamp GIT?

Não. O Timestamp GIT processa apenas hashes de commit do Git, não o código-fonte real. No Modo Standard, o GitHub App requer acesso de leitura ao repositório para buscar o hash do commit, mas nunca lê o conteúdo dos arquivos. No Modo Enterprise ZK, um GitHub Action executa na sua infraestrutura e envia apenas o hash do commit para a API, então o Timestamp GIT tem zero acesso ao seu código.

O que acontece se o Timestamp GIT sair do mercado?

Seus timestamps permanecem válidos para sempre. As provas são ancoradas na blockchain do Bitcoin e são baseadas exclusivamente em SHA-256 e dados de bloco do Bitcoin. Você pode verificá-las independentemente usando ferramentas OpenTimestamps padrão, mesmo que o Timestamp GIT deixe de existir. Os arquivos de recibo .ots são armazenados no seu repositório, então você sempre os terá.

Posso usar o Timestamp GIT com repositórios privados?

Sim. Os planos Pro e Enterprise suportam repositórios privados. Para repositórios privados, os badges de status e links de verificação incluem um HMAC criptografado para que apenas usuários autorizados possam visualizar o status do timestamp. O Modo Enterprise ZK é recomendado para máxima privacidade, pois não requer acesso de leitura ao repositório de origem.

Configure e Esqueça

O carimbo de tempo manual falha porque depende de alguém lembrar de fazê-lo. O valor do estado da técnica criptográfico vem da consistência ao longo de meses e anos, não de um único esforço heroico.

O Timestamp GIT transforma essa consistência em infraestrutura. Instale o GitHub App uma vez, conecte seus repositórios, e o worker noturno cuida da impressão digital, agrupamento, ancoragem no Bitcoin e entrega de provas. Você obtém prova imutável de estado da técnica sem um fardo operacional contínuo.

O plano gratuito cobre repositórios públicos. O Pro adiciona repositórios privados por US$ 49/mês, e o Modo Enterprise ZK custa US$ 199/mês com o fluxo de trabalho do GitHub Action. Para ambientes air-gapped ou regulados, a licença auto-hospedada Docker também está disponível.

Comece a construir seu portfólio de estado da técnica criptográfico hoje: instale o Timestamp GIT GitHub App e conecte seu primeiro repositório.

Posts relacionados

• O Que É Estado da Técnica Criptográfico e Por Que Isso Importa para Software?
• Como Provar que Código Existia em um Momento Específico (Sem Revelá-lo)
• O Que É Prova Criptográfica de Autoria para Código?