2026-10-05 timestamp git blockchain proof

Carimbo de Tempo Automatizado no Git: Como um GitHub App Ancora Cada Commit

Você faz o push de um commit que importa — o núcleo de uma funcionalidade sobre a qual vão te pedir para provar que você a construiu primeiro. Na abordagem manual, esse é o momento em que seu fluxo quebra. Você para, troca de contexto e inicia um pequeno ritual de ferramentas locais e gestão de provas para fixar o commit a um ponto no tempo. Depois você faz isso de novo no próximo commit, e no seguinte, até o dia em que esquece.

Essa é a armadilha do carimbo de tempo manual. Registros de anterioridade só são tão fortes quanto sua densidade e regularidade, e registros baseados em processos humanos não têm nenhuma das duas. Desenvolvedores pulam a etapa durante um período de correria, configuram errado em uma máquina nova, ou nunca configuram no repositório que acaba sendo o que importa. Lacunas na cadeia são exatamente o que um advogado adversário ou um auditor procura.

Este artigo trata de remover o humano desse ciclo por completo com carimbo de tempo automatizado no Git via um GitHub App. Uma instalação, e cada commit em um repositório monitorado é impresso digitalmente e ancorado no Bitcoin toda noite — por uma máquina, em um cronograma, sem ninguém digitar um comando.

Este é um passo a passo de automação, não um mergulho profundo em criptografia. Para o porquê, veja Protegendo a Propriedade Intelectual: Um Guia para Desenvolvedores de Software e Proteção de Anterioridade para Startups de Software: Um Guia. Para a mecânica de verificar uma prova depois, veja Verifique Carimbos de Tempo de Código Sem Compartilhar Seu Código-Fonte.

(Para contexto: a abordagem bruta é executar as ferramentas do OpenTimestamps manualmente, por commit, e gerenciar seus próprios envios de calendário. É o caminho difícil. Tudo abaixo é o caminho automatizado.)

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

O Timestamp GIT é um SaaS gerenciado construído em torno de um GitHub App. Você o instala uma vez em um repositório ou em uma organização inteira, e a automação assume o controle.

Há dois modos de implantação, e você escolhe com base em quanta permissão está disposto a conceder:

Modo Padrão (GitHub App). O GitHub App lê apenas o hash do commit HEAD do seu repositório monitorado — automaticamente, a cada push. As provas são gravadas em um branch dedicado do mesmo repositório ou em um repositório sombra separado. Como o modelo de permissões do GitHub não oferece um escopo de “apenas hash de commit”, este modo exige acesso Somente leitura ao repositório de origem e acesso Leitura e escrita ao repositório de destino onde as provas são gravadas.

Modo Enterprise ZK (GitHub Action). A etapa de coleta passa para o seu próprio CI. Uma GitHub Action de 12 linhas roda nos seus runners, extrai o hash HEAD e envia apenas esse hash para a API do Timestamp GIT. A troca é explícita: você mantém o acesso de leitura para si, e o Timestamp GIT precisa de acesso Leitura e escrita apenas ao repositório de destino. Nenhum código-fonte e nenhum acesso de leitura ao repositório cruzam a fronteira.

Duas coisas que vale notar sobre a configuração:

Nada é instalado nas máquinas dos desenvolvedores. Sem CLI, sem daemon local, sem desvio de configuração por laptop. O app roda na infraestrutura do GitHub e no nosso backend; a Action roda em runners hospedados pelo GitHub ou auto-hospedados.
Não há configuração contínua. Após a instalação, o app detecta novos commits por meio de webhooks. Ninguém precisa lembrar de nada.

Você pode revisar e gerenciar quais repositórios são monitorados na sua página de repositórios após a instalação.

O Pipeline Automatizado: Do Commit à Ancoragem no Bitcoin

Uma vez que o app está instalado, eis o que realmente acontece entre o git push e um arquivo de prova imutável aparecendo no seu repositório.

1. Detecção de commits e agrupamento em lotes

Um webhook dispara em novos commits. O app — ou sua Action, no Modo Enterprise ZK — extrai o hash do commit e o coloca em um armazenamento chave-valor em memória. Esse armazenamento é uma fila, não um registro contábil; ele existe puramente para acumular hashes até que o lote noturno rode.

Apenas o hash se move. Nunca o diff, nunca o conteúdo dos arquivos, nunca o histórico de branches.

2. O worker cron da meia-noite

Toda noite, um worker pega cada hash pendente e:

Agrupa-os por repositório e grava um arquivo de manifesto (.txt) por repositório.
Constrói uma árvore de Merkle nativamente sobre o lote.
Cria provas OpenTimestamps usando servidores de calendário públicos.
Ancora a raiz de Merkle na blockchain do Bitcoin.

Esse último passo é o que torna o registro imutável. Uma vez que a raiz é confirmada em um bloco do Bitcoin, nenhuma entidade — incluindo o Timestamp GIT — pode alterá-la ou forjá-la posteriormente.

3. Entrega das provas

Após a ancoragem, o manifesto e os arquivos de recibo .ots correspondentes são enviados de volta ao seu repositório, seja em um branch dedicado de carimbos de tempo ou em um repositório sombra.

Reserve algumas horas para isso. A confirmação do Bitcoin normalmente leva cerca de 3 horas, então as provas geralmente chegam algumas horas após a execução noturna, em vez de imediatamente.

Modo Enterprise ZK: o único modo com um arquivo de workflow

Este é o único lugar onde você vai olhar para YAML. O assistente de configuração gera o workflow com seu endpoint e segredo pré-preenchidos; ele se parece aproximadamente com isto:

name: Timestamp commit hash
on: [push]
jobs:
  anchor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1
      - name: Send HEAD hash to Timestamp GIT
        env:
          TSG_ENDPOINT: ${{ secrets.TIMESTAMPGIT_ENDPOINT }}
        run: curl -fsS -X POST "$TSG_ENDPOINT" --data "$(git rev-parse HEAD)"

Essa é toda a integração. Há um passo a passo dedicado em GitHub Action para Carimbo de Tempo de Commits: Guia de Configuração se você quiser se aprofundar nesse modo.

Pipelines personalizados: a ZK Commit API

Se você precisa incorporar o carimbo de tempo em algo diferente do fluxo padrão, a ZK Commit API aceita hashes de commit diretamente. Ela é autenticada com HMAC — o valor do hash da URL assinada deve acompanhar a requisição — então uma URL vazada sozinha não é suficiente para gravar no seu registro contábil.

Para automação somente leitura, os endpoints públicos de status são mais simples:

# Last anchored Bitcoin block for a repo
curl -s https://timestampgit.dev/api/statusLast/your-org/your-repo

# Total stamped commit count
curl -s https://timestampgit.dev/api/statusCount/your-org/your-repo

# Combined summary (what the Shields.io badge consumes)
curl -s https://timestampgit.dev/api/statusSummary/your-org/your-repo

Monitoramento e Tratamento de Falhas

Automação que você não consegue auditar não é automação em que você pode confiar em uma disputa. O Timestamp GIT expõe o estado da sua cadeia de provas em três lugares.

O painel público de status

/status/{user}/{repo} mostra a longevidade das provas, a data de ancoragem mais antiga, a regularidade diária e os dados do bloco e da transação do Bitcoin por trás de cada ancoragem. Há um mapa de calor em formato de calendário para que as lacunas sejam visualmente óbvias, além de exportações de CSV de auditoria e certificados em PDF para download.

A regularidade é a métrica a observar. Um mapa de calor com buracos é uma história de anterioridade mais fraca do que um sólido.

Selos de verificação

Você pode incorporar selos Shields.io no seu README para exibir o status de verificação publicamente. O widget em /connected/{user}/{repo} oferece uma pré-visualização ao vivo e o trecho de markdown, e /api/badgeLink/{user}/{repo} retorna as URLs dos selos e o trecho programaticamente.

Repositórios privados anexam um HMAC criptografado às URLs do selo e do status, com escopo para a instância do servidor. Isso significa que o selo ainda é renderizado enquanto apenas usuários autorizados podem resolver os dados de status subjacentes.

Quando uma execução noturna falha

A falha mais provável é o congestionamento da rede Bitcoin atrasando a confirmação. O sistema tenta novamente em vez de descartar o lote. Verifique o estado pelo painel, ou pela API se você estiver integrando isso ao seu próprio alerta:

# Confirm the latest anchored block; a stale value means the last run didn't land
curl -s https://timestampgit.dev/api/statusLast/your-org/your-repo | jq .

Se você precisa de evidência pontual para conformidade, extraia os artefatos diretamente:

# Full audit ledger as CSV
curl -sO https://timestampgit.dev/api/audit/your-org/your-repo

# PDF certificate for a specific date
curl -sO https://timestampgit.dev/api/report/your-org/your-repo/2026-10-04

Qualquer pessoa também pode verificar independentemente o carimbo de tempo de um único dia por meio de /verification/{user}/{repo}/{date}, onde o cálculo completo da cadeia de Merkle acontece localmente no navegador. Ninguém — incluindo o Timestamp GIT — vê o que você verifica.

Ambientes com isolamento de rede (air-gapped)

Se sua postura de segurança não permite um serviço gerenciado de forma alguma, o Timestamp GIT é distribuído como uma imagem Docker. Uma configuração de início rápido com 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 orienta você na conexão do seu GitHub App e na configuração da instância na primeira execução. Uma licença de demonstração por tempo limitado para avaliação está disponível na página Docker License. Carimbo de Tempo em Blockchain Auto-Hospedado com Docker cobre esse caminho em detalhes.

Melhores Práticas para Carimbo de Tempo Automatizado

Faça commits regularmente, em blocos de tamanho razoável. Cada commit adiciona uma folha à árvore de Merkle diária. Uma cadeia densa é um registro de anterioridade mais forte do que quatro commits gigantes por trimestre.
Escreva mensagens de commit significativas. Apenas os hashes recebem carimbo de tempo, mas durante uma auditoria você vai correlacionar provas a funcionalidades. Boas mensagens tornam esse mapeamento trivial.
Configure alertas para ancoragens desatualizadas. Um selo verde deve significar que uma execução recente teve sucesso, não que uma execução aconteceu uma vez em março.
Não mexa no workflow. O maior risco no carimbo de tempo automatizado é alguém “melhorar” o pipeline. A configuração padrão não tem etapas manuais por um motivo.
Recorra ao Modo Enterprise ZK quando seu código-fonte não puder ser lido. Se a conformidade proíbe conceder acesso de leitura ao repositório a um terceiro, rode a Action nos seus próprios runners.
Avise sua equipe de que é automático. Engenheiros que pensam que o carimbo de tempo é uma tarefa manual eventualmente vão tentar fazê-lo manualmente, e é assim que entradas duplicadas ou malformadas aparecem.

Você pode começar em timestampgit.dev — instale o app, conecte um repositório e deixe o primeiro lote noturno rodar.

Perguntas Frequentes

P: Preciso mudar meu fluxo de trabalho no Git para usar o carimbo de tempo automatizado? R: Não. Uma vez que você instala o GitHub App do Timestamp GIT, ele detecta automaticamente novos commits por meio de webhooks e aplica carimbos de tempo a eles toda noite. Você continua fazendo commits como de costume — sem comandos ou etapas extras.

P: O que acontece se eu usar vários branches ou repositórios? R: O GitHub App monitora todos os branches nos repositórios aos quais você concede acesso. Você também pode configurar quais repositórios são monitorados. Para vários repositórios, cada um recebe seu próprio manifesto e arquivos de prova.

P: Meu código-fonte chega a ser exposto ao Timestamp GIT? R: Não. No Modo Padrão, o app lê apenas o hash do commit HEAD — nunca seu código-fonte. No Modo Enterprise ZK, uma GitHub Action na sua infraestrutura envia apenas o hash do commit para a nossa API, então seu código nunca sai do seu ambiente.

P: Quanto tempo leva para um commit receber carimbo de tempo? R: Os hashes de commit são agrupados em lotes e ancorados no Bitcoin uma vez por noite. Após a execução noturna, normalmente leva cerca de 3 horas para a transação do Bitcoin ser confirmada, depois do que os arquivos de prova .ots são enviados de volta ao seu repositório.

Conclusão

O carimbo de tempo manual falha pelo mesmo motivo que toda conformidade manual falha: depende de um humano lembrar, sempre, para sempre. O GitHub App remove essa dependência. Instale-o uma vez, e cada commit em seus repositórios monitorados é impresso digitalmente, agrupado em lote, enraizado em Merkle e ancorado no Bitcoin em um cronograma noturno — com selos, um painel público de status, um CSV de auditoria, certificados em PDF e verificação local no navegador para dar suporte.

Se você está avaliando isso para uma equipe, comece com um único repositório privado e observe a primeira semana de mapa de calor se preencher. Depois decida até onde expandir.

Instale o GitHub App, conecte seu primeiro repositório e deixe o worker da meia-noite fazer o resto.

Posts relacionados

Protegendo a Propriedade Intelectual: Um Guia para Desenvolvedores de Software
Proteção de Anterioridade para Startups de Software: Um Guia
GitHub Action para Carimbo de Tempo de Commits: Guia de Configuração