Timestamp GIT

← Todos os artigos

2026-10-18

Configuração de Timestamp em Blockchain via GitHub App: Instale Uma Vez, Timestamp para Sempre

Configuração de Timestamp em Blockchain via GitHub App: Instale Uma Vez, Timestamp para Sempre
timestamp git blockchain proof

Configuração de Timestamp em Blockchain via GitHub App: Instale Uma Vez, Timestamp Para Sempre

A tarefa em uma frase: instale o GitHub App do Timestamp GIT em um repositório para que cada commit que você enviar seja automaticamente ancorado na blockchain do Bitcoin toda noite — sem ferramentas de linha de comando, sem passos manuais, sem mudanças na forma como sua equipe trabalha.

Você pode, sem dúvida, fazer isso do jeito difícil: executar as ferramentas do OpenTimestamps por conta própria, gerenciar calendários, construir seu próprio agrupamento Merkle e acompanhar as confirmações do Bitcoin. Isso é um trabalho de meio período. O Timestamp GIT existe justamente para que isso não seja trabalho seu. Este guia percorre o caminho de configuração que recomendamos: uma instalação, uma seleção de repositório, uma tela de configuração e, depois, um pipeline noturno com o qual você nunca mais precisa se preocupar.

Ao final, você terá um recibo .ots diário para seus commits, um selo de verificação no seu README e um painel de status público que qualquer pessoa — um advogado, um auditor, um cliente — pode consultar sem precisar de conta.

O Que Você Vai Configurar (e Por Que É um Trabalho Único)

A tarefa exata: conectar um repositório ao GitHub App para que a detecção de commits, o agrupamento de hashes, a ancoragem no Bitcoin e a entrega das provas aconteçam sem você.

O que você ganha com isso:

  • Um recibo .ots imutável por dia — uma prova criptográfica de que um conjunto específico de hashes de commit existia em uma data específica.
  • Um selo de verificação que você pode colocar no seu README para que o status da prova seja público.
  • Um painel de status com datas de ancoragem, dados de bloco e transação do Bitcoin, regularidade diária e exportações de auditoria para download.

A divisão do trabalho vale a pena internalizar, porque explica por que a configuração é um trabalho único:

  1. O GitHub App detecta commits via webhooks.
  2. O Timestamp GIT agrupa os hashes de commit à meia-noite, constrói uma árvore Merkle e ancora a raiz Merkle no Bitcoin usando o protocolo OpenTimestamps.
  3. Os arquivos de manifesto e de recibo .ots são enviados de volta para um branch dedicado timestamps ou para um repositório sombra que você controla.

Existem dois modos de implantação, e este guia segue o primeiro:

  • Modo padrão (GitHub App) — totalmente gerenciado, sem código no seu CI, lê apenas o hash do commit HEAD dos repositórios monitorados.
  • Modo Enterprise ZK — uma pequena GitHub Action rodando na sua própria infraestrutura envia apenas os hashes de commit para a API do Timestamp GIT, e é necessário apenas acesso de leitura e escrita ao repositório de provas de destino.

Se você precisa do contexto conceitual sobre por que tudo isso importa — trolls de patentes, disputas trabalhistas, alegações de “clean room” — leia primeiro O Que É Prior Art Criptográfico?. Este artigo assume que você já decidiu que quer isso e agora quer que funcione.

Pré-requisitos Antes de Instalar

  • Uma conta do GitHub com direitos de administrador no repositório de destino (público ou privado).
  • Uma conta do Timestamp GIT com um plano compatível com a visibilidade do seu repositório: Open Source (gratuito, repositórios públicos), Pro Agency ($49/mês, repositórios privados) ou Enterprise ZK ($199/mês, GitHub Actions).
  • Uma decisão sobre onde as provas devem ficar: um branch dedicado timestamps no mesmo repositório ou um repositório sombra separado.
  • Clareza sobre o modelo de permissões: o modo padrão exige acesso somente leitura ao repositório de origem e acesso de leitura e escrita ao repositório de destino. O modo Enterprise ZK exige acesso de leitura e escrita apenas ao repositório de destino, além de uma GitHub Action instalada no seu repositório de origem.
  • Basicamente nada mais. Não há nada para instalar nas máquinas dos desenvolvedores. Sem configuração local, sem hooks, sem variáveis de ambiente por desenvolvedor.

Passo 1 — Instale o GitHub App do Timestamp GIT

  1. Navegue até a listagem do GitHub App do Timestamp GIT e clique em Install.
  2. Escolha a conta ou organização do GitHub que possui o repositório.
  3. Selecione Only select repositories e escolha o(s) repositório(s) que deseja monitorar — ou conceda acesso a todos os repositórios da conta.
  4. Aprove as permissões solicitadas. No modo padrão, isso significa acesso somente leitura ao repositório de origem (o sistema de permissões do GitHub não tem um escopo de “apenas hash de commit”) e acesso de leitura e escrita ao repositório de destino onde as provas são gravadas.
  5. Confirme o redirecionamento de volta para o Timestamp GIT e aguarde a mensagem de sucesso.

Essa é a instalação. É um fluxo normal no estilo OAuth do GitHub App e leva cerca de um minuto.

Passo 2 — Conecte e Configure Seu Repositório

Vá para Your Repositories (/repos) e confirme que o repositório recém-acessível aparece na lista. Se ele não aparecer, você quase certamente selecionou a conta errada durante a instalação.

Em seguida, abra a página de conexão do repositório e configure o destino das suas provas:

  • Mesmo repositório, branch dedicado — as provas ficam em um branch timestamps junto com seu código. Simples, autocontido, fácil de encontrar.
  • Repositório sombra separado — as provas ficam em um repositório à sua escolha. Útil quando o repositório de origem tem um público restrito ou quando você quer um registro central de provas em vários projetos.

Se você estiver usando um repositório sombra, crie-o ou selecione-o e confirme que o Timestamp GIT tem acesso de leitura e escrita a ele. Uma permissão ausente ou revogada aqui é a causa mais comum de “por que nada está aparecendo” mais adiante.

Enquanto estiver nesta página, ative o selo do README. A página de conexão exibe uma prévia ao vivo do selo Shields.io e fornece o trecho exato de markdown — não escreva as URLs à mão, pois repositórios privados exigem um componente HMAC específico da instância.

Salve a configuração. O app agora está armado: a partir deste ponto, os webhooks o informam sobre cada novo commit no branch monitorado.

Passo 3 — Deixe a Ancoragem Noturna Rodar (e Saiba o Que Esperar)

Nada mais é exigido de você. Aqui está o que acontece à meia-noite:

  1. Detecção de commits — o GitHub App já capturou os novos hashes de commit via webhooks.
  2. Fila de hashes — os hashes ficam em um armazenamento de chave-valor em memória, aguardando a janela de agrupamento.
  3. Worker cron da meia-noite — os hashes pendentes são agrupados, um arquivo de manifesto .txt é gerado por repositório, uma árvore Merkle é construída nativamente, provas OpenTimestamps são criadas usando calendários OTS públicos e a raiz Merkle é ancorada na blockchain do Bitcoin.
  4. Entrega das provas — os arquivos de manifesto e de recibo .ots são enviados de volta para o branch timestamps do seu repositório ou para o repositório sombra.

O que aparece no repositório de destino é mais ou menos assim:

timestamps/
  manifests/
    2026-10-18.txt        # the commit hashes batched that day
  proofs/
    2026-10-18.txt.ots    # the OpenTimestamps receipt for that manifest

Expectativas de tempo. O agrupamento roda à meia-noite, e a confirmação do Bitcoin leva várias horas — normalmente cerca de três. Então, se você enviar às 09:00, espere que as provas cheguem no meio da manhã do dia seguinte. Isso é uma propriedade do Bitcoin, não um bug do pipeline.

O que sai do seu repositório: apenas hashes de commit. O Timestamp GIT nunca lê, copia ou armazena seu código-fonte. A origem permanece no GitHub (ou, no modo Enterprise ZK, inteiramente no seu próprio ambiente) e apenas o hash é carimbado.

E então isso se repete. Toda noite, para sempre, para cada commit futuro. Você instalou uma vez; o pipeline cuida do resto.

Passo 4 — Adicione o Selo de Verificação ao Seu README

Pegue o trecho de markdown na página de conexão do repositório — os mesmos dados estão disponíveis programaticamente no endpoint autenticado GET /api/badgeLink/{user}/{repo}, que retorna URLs de selo e trechos de markdown.

O trecho tem este formato (use o botão de copiar; as URLs reais são específicas da instância e do repositório, especialmente para repositórios privados):

[![Bitcoin timestamped](<badge-url-from-badgeLink>)](<status-page-url>)

Cole no seu README, faça commit e envie. Qualquer pessoa que clicar no selo chega à visualização pública de verificação — sem conta, sem login, sem conhecimento especial necessário.

Uma observação sobre repositórios privados. As URLs de status para repositórios privados acrescentam um HMAC criptografado. Isso significa que apenas usuários autorizados podem ver o status da prova, enquanto a âncora Bitcoin subjacente permanece publicamente verificável por qualquer pessoa que tenha o arquivo .ots. O HMAC é específico da sua instância de servidor, e é por isso que você deve copiar a URL do selo em vez de construí-la.

Opcional, mas legal: incorpore o mesmo selo em um site de documentação interno ou em um painel de engenharia. É apenas uma URL de imagem mais um link.

Passo 5 — (Opcional) Auto-hospede com Docker para Ambientes Air-Gapped

Escolha a auto-hospedagem quando quiser segurança máxima, uma rede air-gapped ou garantias estritas de residência de dados que um serviço gerenciado não consegue satisfazer.

Uma configuração Docker Compose de início rápido é assim:

services:
  timestampgit:
    image: rue1401/timestampgit:prod
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    restart: unless-stopped
  valkey:
    image: valkey/valkey:8
    restart: unless-stopped

Depois, baixe e inicie:

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

Após a inicialização, a aplicação fica disponível em http://localhost:8080. Na primeira execução, um assistente de configuração orienta você na conexão do seu GitHub App e na configuração da sua instância.

Uma licença de demonstração por tempo limitado para avaliação está disponível ao enviar o formulário de solicitação na página Docker License (/docker-license) com seu nome, empresa, e-mail e um número de telefone opcional. Um arquivo de licença de demonstração por tempo limitado pode ser baixado após a aprovação.

Como Confirmar Que Funcionou

Dê um ciclo completo (agrupamento da meia-noite mais cerca de três horas) e depois verifique:

  • Painel de status — abra /status/{user}/{repo}. Você deve ver a longevidade das provas, a data de ancoragem mais antiga, a regularidade diária, dados de bloco e transação do Bitcoin e um mapa de calor em calendário.
  • CSV de auditoria — GET /api/audit/{user}/{repo} baixa o registro de auditoria completo.
  • Certificado em PDF — GET /api/report/{user}/{repo}/{date} gera um certificado para um dia específico.
  • Percurso da cadeia Merkle — /verification/{user}/{repo}/{date} mostra a verificação multinível passo a passo. Toda a computação acontece localmente no seu navegador, então ninguém — incluindo nós — vê o que você verifica.
  • Endpoints públicos de status — verificações rápidas de sanidade:
curl -s https://timestampgit.dev/api/statusLast/{user}/{repo}
curl -s https://timestampgit.dev/api/statusCount/{user}/{repo}
curl -s https://timestampgit.dev/api/statusSummary/{user}/{repo}

statusLast retorna o último bloco do Bitcoin ancorado, statusCount retorna a contagem total de commits registrados e carimbados, e statusSummary reúne os dados para o Shields.io.

Se você quiser o passo a passo mais detalhado e offline para transformar um arquivo .ots em uma altura de bloco do Bitcoin verificada, cobrimos isso separadamente em Como Verificar uma Prova de Timestamp do Bitcoin Localmente.

Solução de Problemas Comuns de Configuração

Nenhuma prova aparecendo após 24 horas. Confirme que o app realmente tem acesso ao repositório correto (verifique /repos) e confirme que pelo menos um commit foi enviado após a instalação. Commits anteriores à instalação nunca foram enviados para a fila de hashes.

Selo aparece como “unknown”. Verifique o slug do repositório na URL do selo. Para repositórios privados, certifique-se de que o componente HMAC criptografado está presente — uma URL reduzida falhará na autorização e não retornará status.

Envios para o repositório sombra falham. O Timestamp GIT precisa de acesso de leitura e escrita ao repositório de destino. Verifique novamente as permissões de instalação especificamente no repositório sombra; as permissões do repositório de origem não se estendem a ele.

O modo Enterprise ZK não produz nada. Nesse modo, não há detecção de commits baseada em webhook. Se a GitHub Action não estiver instalada no repositório de origem e enviando ativamente hashes para a API, nenhum hash chega ao serviço.

As provas estão atrasadas em algumas horas. Esperado. O agrupamento roda à meia-noite e a confirmação do Bitcoin normalmente leva cerca de três horas. Atrasos aqui são temporização da blockchain, não uma falha.

FAQ

Preciso instalar alguma ferramenta de linha de comando ou executar comandos do OpenTimestamps?

Não. O Timestamp GIT é um GitHub App gerenciado: você o instala uma vez, e cada commit em um repositório monitorado é automaticamente ancorado no Bitcoin toda noite. Não há ferramentas de linha de comando, nem comandos do OpenTimestamps, nem nada para instalar nas máquinas dos desenvolvedores.

Posso usar o GitHub App com repositórios privados?

Sim. Repositórios privados são suportados no plano Pro Agency. As URLs de status para repositórios privados acrescentam um HMAC criptografado para que apenas usuários autorizados possam ver o status da prova.

Quanto tempo leva até minha primeira prova de timestamp aparecer?

Os commits são agrupados e ancorados por um worker cron da meia-noite. A confirmação do Bitcoin normalmente leva cerca de três horas, então os arquivos de manifesto e de recibo .ots são enviados de volta ao seu repositório algumas horas após o agrupamento rodar.

O que acontece com minhas provas se o Timestamp GIT encerrar as atividades?

As provas são independentes de fornecedor. Elas dependem apenas de SHA-256 e dos dados de bloco do Bitcoin via protocolo OpenTimestamps, então você pode verificá-las offline usando ferramentas padrão mesmo que o serviço não exista mais.

Conclusão

O ponto central de uma configuração de timestamp em blockchain via GitHub App é que ela deve ser entediante: instale uma vez, selecione um repositório, escolha onde as provas vão e deixe um job noturno fazer o resto. Tudo depois do passo dois é esperar o Bitcoin confirmar.

Nesse ponto, você tem algo que a maioria das equipes não tem — prova matematicamente inegável de quando seu código existiu, verificável offline, sem que seu código-fonte jamais saia do seu repositório. Isso é prior art que você pode entregar a um advogado, um auditor ou um cliente sem que um único desenvolvedor mude seu fluxo de trabalho.

Instale o GitHub App primeiro no seu repositório mais valioso e depois expanda a partir dali. Se você preferir rodá-lo dentro do seu próprio perímetro, a licença auto-hospedada via Docker é o mesmo produto com a sua infraestrutura por baixo.

Posts relacionados

EU label: AI-generated content