Carimbe Automaticamente Cada Commit do Git com um GitHub App
Cada vez que você faz um commit, o Git já gera um hash único que identifica o estado exato do seu repositório. Esse hash é uma impressão digital criptograficamente segura do seu trabalho naquele momento. O que ele não é, por si só, é uma prova de quando o trabalho existiu. Transformar esse hash em evidência imutável e pronta para uso judicial costumava significar um processo manual: executar comandos extras, monitorar a saída, armazenar arquivos de recibo e repetir tudo isso a cada commit.
A alternativa automatizada é mais simples: instale um GitHub App uma única vez, selecione seus repositórios e deixe que cada commit futuro seja ancorado ao blockchain do Bitcoin enquanto você dorme.
O Timestamp GIT é um serviço gerenciado construído em torno dessa ideia. Ele automatiza totalmente o protocolo OpenTimestamps para que você nunca precise usar uma CLI, construir uma transação Bitcoin ou gerenciar arquivos de prova manualmente. Este artigo cobre a configuração única, o pipeline de automação noturno, monitoramento, boas práticas e perguntas comuns.
Configuração Única: Instale o Timestamp GIT GitHub App
Todo o produto é projetado em torno de um único fluxo de configuração. Depois disso, fazer commit do código é a única ação que você precisa realizar.
Modo Padrão: GitHub App
- Instale o Timestamp GIT GitHub App a partir do GitHub Marketplace.
- Conceda as permissões solicitadas durante a instalação. No Modo Padrão, o app requer acesso somente leitura ao repositório de origem porque as permissões do GitHub não oferecem um escopo apenas para hash de commit. O Timestamp GIT nunca lê, copia ou armazena seu código-fonte.
- Selecione os repositórios que deseja monitorar. Repositórios públicos são suportados no plano Open Source gratuito; repositórios privados exigem um plano pago.
- Escolha onde os arquivos de prova devem ficar. Você pode armazená-los em um branch dedicado
timestampsno mesmo repositório ou em um repositório de destino separado. Um repositório sombra separado mantém o histórico do seu código-fonte principal limpo.
Após a instalação, o GitHub App monitora os repositórios selecionados automaticamente. Não há ferramentas de CLI para instalar, nem comandos OpenTimestamps para aprender, nem etapas manuais para executar após a configuração.
Modo Enterprise ZK: GitHub Action
Para organizações que desejam isolamento máximo, o Timestamp GIT oferece um Modo Enterprise ZK. Em vez de dar ao GitHub App acesso de leitura ao seu repositório de origem, uma GitHub Action é executada na sua própria infraestrutura e envia apenas o hash do commit para a API do Timestamp GIT.
O formato do workflow é assim:
name: timestamp-git-zk
on:
push:
jobs:
timestamp:
runs-on: ubuntu-latest
steps:
- name: Push commit hash to Timestamp GIT
env:
COMMIT_SHA: ${{ github.sha }}
REPO: ${{ github.repository }}
run: |
curl -fsS -X POST \
-H "Authorization: Bearer ${{ secrets.TIMESTAMP_GIT_HMAC }}" \
-H "Content-Type: application/json" \
-d "{\"repo\":\"$REPO\",\"hash\":\"$COMMIT_SHA\"}" \
"${{ vars.TIMESTAMP_GIT_API_URL }}"
A URL exata da API, os identificadores do repositório e o segredo HMAC são fornecidos durante o assistente de configuração Enterprise. A parte importante é o que o workflow não faz: ele nunca envia código-fonte, arquivos ou conteúdo do repositório. Ele envia um hash de commit e nada mais.
Nesse modo, o Timestamp GIT não precisa de nenhum acesso de leitura ao seu repositório de origem.
O Pipeline Automatizado: Do Commit à Âncora no Bitcoin
Uma vez que o GitHub App ou a GitHub Action esteja em funcionamento, o carimbo de tempo se torna uma tarefa em segundo plano.
1. Detecção de Commit
No Modo Padrão, o GitHub App recebe webhooks quando novos commits chegam aos seus repositórios monitorados. No Modo Enterprise ZK, sua GitHub Action envia o hash do commit diretamente para a API.
2. Fila de Hashes
Os hashes de commit detectados entram em um armazenamento chave-valor em memória, onde aguardam o processamento em lote. O Timestamp GIT não escaneia seu código, não clona seu repositório completo nem inspeciona o conteúdo dos arquivos.
3. Worker Cron Noturno
A cada noite, um worker agrupa todos os hashes pendentes por repositório. Para cada repositório, ele cria um arquivo de manifesto, constrói uma árvore Merkle nativamente e cria provas OpenTimestamps usando calendários OTS públicos.
4. Ancoragem no Bitcoin
A raiz Merkle do lote diário é incorporada em uma transação Bitcoin usando o protocolo OpenTimestamps. Uma vez que essa transação é confirmada em um bloco Bitcoin, a âncora se torna imutável. Nenhuma entidade — incluindo o Timestamp GIT — pode alterá-la ou falsificá-la.
A confirmação no Bitcoin normalmente leva cerca de três horas. Isso significa que um commit feito durante o dia de trabalho geralmente está ancorado na manhã seguinte.
5. Entrega da Prova
Após a confirmação, o manifesto e os arquivos de recibo .ots são enviados de volta para o local de prova configurado: um branch dedicado de timestamps ou um repositório sombra. Os arquivos de prova são pequenos arquivos de texto e binários que comprovam que o hash do seu commit existia antes do bloco Bitcoin ser minerado.
Você pode consultar o último bloco ancorado de um repositório público com uma chamada de API simples:
curl -s https://timestampgit.dev/api/statusLast/your-org/your-repo
A resposta contém as informações do último bloco Bitcoin ancorado. Endpoints adicionais retornam contagens totais de commits carimbados, resumos de status combinados e dados completos da cadeia Merkle para um dia específico.
Monitoramento e Tratamento de Falhas
A automação só é útil quando você consegue ver que ela está funcionando.
Painel de Status do Repositório
Cada repositório conectado recebe uma página de status pública ou autenticada. O painel mostra:
- Longevidade da prova: até onde sua data de âncora mais antiga remonta
- Regularidade diária: se os commits estão sendo agrupados de forma consistente
- Dados de bloco e transação Bitcoin para cada âncora
- Um mapa de calor em calendário para uma visão visual da atividade
A página de status oferece uma resposta rápida à pergunta: “Os commits de ontem foram ancorados?”
Exportações de Auditoria e Conformidade
O Timestamp GIT fornece registros de auditoria para download:
# Download de um livro-razão de auditoria completo como CSV
curl -o audit.csv https://timestampgit.dev/api/audit/your-org/your-repo
Você também pode baixar um certificado PDF para uma data específica. Essas exportações são úteis para arquivos de conformidade, revisões legais ou documentação de PI em nível de diretoria.
Tratamento de Commits Perdidos
Em operação normal, um commit que perde o lote noturno — por exemplo, porque a entrega de um webhook foi atrasada — é capturado na próxima execução noturna. O design orientado a lotes significa que falhas temporárias não exigem que você execute nada manualmente novamente.
Privacidade de Repositórios Privados
Para repositórios privados, os endpoints de status são protegidos com um HMAC criptografado. Somente usuários autorizados com a assinatura de URL correta podem visualizar o status do repositório. O HMAC é específico da instância do servidor, portanto os dados de status não são expostos ao público.
Boas Práticas para Carimbo de Tempo Automatizado
Um GitHub App pode automatizar a mecânica, mas algumas escolhas de configuração tornam a evidência mais forte e mais fácil de gerenciar.
Monitore Todos os Repositórios Ativos
Não monitore apenas branches de release. Disputas de estado da técnica frequentemente dependem de um commit experimental inicial, um branch em andamento ou um protótipo rápido. Ative o monitoramento em todos os repositórios onde código significativo é escrito.
Use um Repositório Sombra Dedicado
Se você não quer que os arquivos de prova poluam seu repositório principal, configure o Timestamp GIT para enviar as provas para um repositório separado. Isso mantém o histórico do código-fonte limpo e ainda oferece a advogados, auditores e equipes de conformidade um único lugar para procurar recibos de prova.
Escolha o Modo Enterprise ZK para Isolamento Máximo
Se seu código é altamente sensível ou sua política de segurança proíbe acesso de leitura de terceiros aos repositórios de origem, use o Modo Enterprise ZK. A abordagem com GitHub Action significa que seu código-fonte nunca sai do seu ambiente. O Timestamp GIT só recebe hashes de commit.
Arquive CSVs de Auditoria Regularmente
Os arquivos .ots são a prova criptográfica, mas os CSVs de auditoria são o registro legível por humanos. Baixe-os em uma programação definida e armazene-os junto com seus outros documentos de conformidade. Em uma disputa, ter um livro-razão cronológico limpo economiza tempo.
Adicione Selos de Verificação ao seu README
Repositórios públicos podem exibir um selo de verificação que vincula à página de status do Timestamp GIT. A página de conexão do repositório fornece URLs de selo e trechos de Markdown. Um selo típico se parece com:
[](https://timestampgit.dev/status/your-org/your-repo)
Qualquer pessoa que visualize o repositório pode clicar e verificar o status atual do carimbo de tempo sem instalar nada.
Perguntas Frequentes
Como o GitHub App carimba meus commits automaticamente?
Uma vez instalado, o GitHub App monitora seus repositórios selecionados. A cada noite, ele coleta todos os novos hashes de commit, cria uma árvore Merkle, ancora a raiz no blockchain do Bitcoin via OpenTimestamps e envia os arquivos de prova .ots de volta para o seu repositório. Nenhuma etapa manual é necessária.
O GitHub App precisa de acesso ao meu código-fonte?
No Modo Padrão, o GitHub App requer acesso somente leitura ao repositório de origem para ler os hashes de commit, porque as permissões do GitHub exigem esse escopo. No entanto, o Timestamp GIT nunca lê, copia ou armazena seu código-fonte — ele processa apenas o hash do commit. No Modo Enterprise ZK, uma GitHub Action é executada na sua infraestrutura e envia apenas o hash do commit para a API, portanto o app não tem nenhum acesso ao seu repositório de origem.
Quanto tempo leva para um commit ser carimbado no Bitcoin?
Os commits são agrupados em lotes noturnos. Após o processamento do lote, a transação Bitcoin é transmitida. A confirmação no blockchain do Bitcoin normalmente leva cerca de três horas, após as quais os arquivos de prova são gravados no seu repositório. Um commit feito durante o dia geralmente terá sua prova de carimbo de tempo disponível na manhã seguinte.
Posso verificar o carimbo de tempo sem depender do Timestamp GIT?
Sim. A prova é um arquivo OpenTimestamps .ots padrão. Você pode baixá-lo e verificá-lo localmente usando qualquer ferramenta de verificação OpenTimestamps contra o blockchain do Bitcoin. O Timestamp GIT também fornece uma página de verificação baseada na web e certificados PDF por conveniência.
Conclusão: Configure e Esqueça
O Timestamp GIT transforma a proteção criptográfica de estado da técnica de uma tarefa manual em um processo automático em segundo plano. Instale o GitHub App uma vez, selecione seus repositórios e cada commit futuro fluirá pelo mesmo pipeline: detecção de hash, agrupamento noturno, construção da árvore Merkle, ancoragem no Bitcoin e entrega da prova.
O modelo de segurança é intencionalmente de conhecimento zero. Seu código-fonte nunca é lido ou armazenado. O Modo Padrão processa apenas hashes de commit, e o Modo Enterprise ZK mantém até mesmo esses hashes sob seu controle até que você os envie para a API.
Os preços cobrem os casos comuns: Open Source é gratuito para repositórios públicos, Pro Agency custa US$ 49/mês para repositórios privados e Enterprise ZK custa US$ 199/mês com suporte a GitHub Actions. Para ambientes air-gapped ou autogerenciados, uma licença Docker self-hosted também está disponível.
Se você ainda está criando carimbos de tempo manualmente para commits individuais, o caminho mais rápido é instalar o Timestamp GIT GitHub App ou solicitar uma licença Docker self-hosted para controle máximo.
Posts relacionados
- Timestamp GIT vs OpenTimestamps Manual: Qual é Melhor?
- Como Provar Estado da Técnica para Software: Um Guia para Desenvolvedores
- Como Proteger Seu Software de Trolls de Patentes
