2026-10-05 timestamp git blockchain proof

Timestamping Git automatizzato: come una GitHub App ancora ogni commit

Fai il push di un commit che conta — il nucleo di una funzionalità di cui ti verrà chiesto di dimostrare di averla costruita per primo. Con l’approccio manuale, è proprio in quel momento che il tuo flusso si interrompe. Ti fermi, cambi contesto e inizi un piccolo rituale di strumenti locali e gestione delle prove per fissare il commit a un punto nel tempo. Poi lo rifai al commit successivo, e a quello dopo, finché un giorno te ne dimentichi.

Questa è la trappola del timestamping manuale. I registri di prior art sono forti solo quanto la loro densità e la loro regolarità, e i registri basati su processi umani non hanno né l’una né l’altra. Gli sviluppatori saltano il passaggio durante un periodo di pressione, lo configurano male su una nuova macchina, o non lo impostano mai sul repository che si rivela poi quello che conta. Le lacune nella catena sono esattamente ciò che cerca un avvocato avversario o un revisore.

Questo articolo parla di rimuovere completamente l’essere umano da quel ciclo con il timestamping Git automatizzato tramite una GitHub App. Una sola installazione, e ogni commit su un repository monitorato viene improntato e ancorato in Bitcoin ogni notte — da una macchina, secondo una pianificazione, senza che nessuno digiti un comando.

Questa è una guida all’automazione, non un’analisi approfondita di crittografia. Per il perché, vedi Proteggere la proprietà intellettuale: una guida per sviluppatori software e Protezione della prior art per le startup software: una guida. Per i meccanismi di verifica successiva di una prova, vedi Verificare i timestamp del codice senza condividere il codice sorgente.

(Per contesto: l’approccio grezzo consiste nell’eseguire manualmente gli strumenti OpenTimestamps, per ogni commit, e nel gestire da soli le proprie sottomissioni ai calendar server. È la via difficile. Tutto ciò che segue è il percorso automatizzato.)

Configurazione una tantum: installa la GitHub App e dimenticatene

Timestamp GIT è un SaaS gestito costruito attorno a una GitHub App. La installi una volta sola su un repository o su un’intera organizzazione, e l’automazione prende il sopravvento.

Ci sono due modalità di deployment, e scegli in base a quanto accesso sei disposto a concedere:

Modalità Standard (GitHub App). La GitHub App legge solo l’hash del commit HEAD del tuo repository monitorato — automaticamente, a ogni push. Le prove vengono scritte in un branch dedicato dello stesso repo o in un repository shadow separato. Poiché il modello di permessi di GitHub non offre uno scope “solo hash del commit”, questa modalità richiede accesso in sola lettura al repo sorgente e accesso in lettura-scrittura al repo di destinazione dove atterrano le prove.

Modalità Enterprise ZK (GitHub Action). Il passaggio di raccolta si sposta nella tua CI. Una GitHub Action di 12 righe viene eseguita sui tuoi runner, estrae l’hash HEAD e invia solo quell’hash all’API di Timestamp GIT. Il compromesso è esplicito: mantieni l’accesso in lettura per te, e Timestamp GIT necessita di accesso in lettura-scrittura solo al repo di destinazione. Nessun codice sorgente e nessun accesso in lettura al repository attraversa mai il confine.

Due cose degne di nota sulla configurazione:

Non viene installato nulla sulle macchine degli sviluppatori. Nessuna CLI, nessun daemon locale, nessuna deriva di configurazione da portatile a portatile. L’app gira sull’infrastruttura di GitHub e sul nostro backend; l’Action gira su runner ospitati da GitHub o self-hosted.
Non c’è configurazione continua. Dopo l’installazione, l’app rileva i nuovi commit tramite webhook. Nessuno deve ricordarsi nulla.

Puoi rivedere e gestire quali repository sono monitorati dalla pagina dei tuoi repository dopo l’installazione.

La pipeline automatizzata: dal commit all’ancoraggio in Bitcoin

Una volta installata l’app, ecco cosa succede effettivamente tra il git push e la comparsa di un file di prova immutabile nel tuo repo.

1. Rilevamento dei commit e raggruppamento in batch

Un webhook scatta sui nuovi commit. L’app — o la tua Action, in modalità Enterprise ZK — estrae l’hash del commit e lo inserisce in un archivio chiave-valore in memoria. Quell’archivio è una coda, non un registro; esiste puramente per accumulare hash fino all’esecuzione del batch notturno.

Si muove solo l’hash. Mai il diff, mai il contenuto dei file, mai la cronologia dei branch.

2. Il worker cron di mezzanotte

Ogni notte, un worker preleva ogni hash in sospeso e:

Li raggruppa per repository e scrive un file manifest (.txt) per repo.
Costruisce un Merkle tree nativamente sul batch.
Crea le prove OpenTimestamps usando i calendar server pubblici.
Ancora la radice di Merkle nella blockchain di Bitcoin.

Quest’ultimo passaggio è quello che rende il registro immutabile. Una volta che la radice è confermata in un blocco Bitcoin, nessuna entità — inclusa Timestamp GIT — può alterarla o falsificarla a posteriori.

3. Consegna delle prove

Dopo l’ancoraggio, il manifest e i corrispondenti file di ricevuta .ots vengono respinti nel tuo repository, in un branch timestamps dedicato o in un repository shadow.

Metti in conto qualche ora per questo. La conferma di Bitcoin richiede tipicamente circa 3 ore, quindi le prove atterrano generalmente qualche ora dopo l’esecuzione notturna anziché immediatamente.

Modalità Enterprise ZK: l’unica modalità con un file di workflow

Questo è l’unico punto in cui guarderai mai dello YAML. La procedura guidata di configurazione genera il workflow con il tuo endpoint e il tuo secret precompilati; assomiglia all’incirca a questo:

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)"

Questa è tutta l’integrazione. C’è una guida dedicata in GitHub Action per il timestamping dei commit: guida alla configurazione se vuoi approfondire questa modalità.

Pipeline personalizzate: la ZK Commit API

Se devi integrare il timestamping in qualcosa di diverso dal flusso standard, la ZK Commit API accetta direttamente gli hash dei commit. È autenticata con HMAC — il valore hash dell’URL firmato deve accompagnare la richiesta — quindi un URL trapelato da solo non basta per scrivere nel tuo registro.

Per l’automazione in sola lettura, gli endpoint pubblici di stato sono più semplici:

# 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

Monitoraggio e gestione dei guasti

Un’automazione che non puoi verificare non è un’automazione di cui ti puoi fidare in una disputa. Timestamp GIT espone lo stato della tua catena di prove in tre punti.

La dashboard pubblica di stato

/status/{user}/{repo} mostra la longevità delle prove, la data di ancoraggio più antica, la regolarità giornaliera e i dati del blocco e della transazione Bitcoin dietro ogni ancoraggio. C’è una heatmap a calendario così che le lacune siano visivamente evidenti, più esportazioni scaricabili di CSV di audit e certificati PDF.

La regolarità è la metrica da tenere d’occhio. Una heatmap con dei buchi è una storia di prior art più debole di una solida.

Badge di verifica

Puoi incorporare i badge Shields.io nel tuo README per mostrare pubblicamente lo stato di verifica. Il widget su /connected/{user}/{repo} ti offre un’anteprima dal vivo e lo snippet markdown, e /api/badgeLink/{user}/{repo} restituisce gli URL dei badge e lo snippet in modo programmatico.

I repository privati aggiungono un HMAC cifrato agli URL del badge e dello stato, con scope sull’istanza del server. Questo significa che il badge viene comunque renderizzato mentre solo gli utenti autorizzati possono risolvere i dati di stato sottostanti.

Quando un’esecuzione notturna fallisce

Il guasto più probabile è la congestione della rete Bitcoin che ritarda la conferma. Il sistema riprova anziché scartare il batch. Controlla lo stato tramite la dashboard, o tramite l’API se stai integrando questo nel tuo sistema di allerta:

# 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 hai bisogno di prove puntuali per la conformità, estrai direttamente gli artefatti:

# 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

Chiunque può anche verificare in modo indipendente il timestamp di un singolo giorno tramite /verification/{user}/{repo}/{date}, dove il calcolo completo della catena di Merkle avviene localmente nel browser. Nessuno — inclusa Timestamp GIT — vede ciò che verifichi.

Ambienti air-gapped

Se il tuo profilo di sicurezza non permette affatto un servizio gestito, Timestamp GIT è distribuito come immagine Docker. Una configurazione Docker Compose di avvio rapido assomiglia a questo:

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

L’applicazione è disponibile su http://localhost:8080 dopo l’avvio, e una procedura guidata di configurazione ti accompagna nel collegamento della tua GitHub App e nella configurazione dell’istanza al primo avvio. Una licenza demo a tempo limitato per la valutazione è disponibile tramite la pagina Docker License. Timestamping blockchain self-hosted con Docker copre quel percorso in dettaglio.

Buone pratiche per il timestamping automatizzato

Fai commit regolarmente, in blocchi di dimensioni ragionevoli. Ogni commit aggiunge una foglia al Merkle tree giornaliero. Una catena densa è un registro di prior art più forte di quattro commit giganteschi a trimestre.
Scrivi messaggi di commit significativi. Solo gli hash vengono timestampati, ma durante un audit dovrai correlare le prove alle funzionalità. Dei buoni messaggi rendono quella mappatura banale.
Configura un sistema di allerta sugli ancoraggi obsoleti. Un badge verde dovrebbe significare che un’esecuzione recente è riuscita, non che un’esecuzione è avvenuta una volta a marzo.
Lascia stare il workflow. Il rischio singolo più grande nel timestamping automatizzato è qualcuno che “migliora” la pipeline. La configurazione predefinita non ha passaggi manuali per un motivo.
Ricorri alla modalità Enterprise ZK quando il tuo sorgente non può essere letto. Se la conformità vieta di concedere a terzi l’accesso in lettura al repository, esegui l’Action sui tuoi runner.
Di’ al tuo team che è automatico. Gli ingegneri che pensano che il timestamping sia un compito manuale prima o poi proveranno a farlo manualmente, ed è così che compaiono voci duplicate o malformate.

Puoi iniziare da timestampgit.dev — installa l’app, collega un repository e lascia che il primo batch notturno venga eseguito.

FAQ

D: Devo cambiare il mio flusso di lavoro Git per usare il timestamping automatizzato? R: No. Una volta installata la GitHub App di Timestamp GIT, rileva automaticamente i nuovi commit tramite webhook e li timestampa ogni notte. Continui a fare commit come al solito — nessun comando o passaggio aggiuntivo.

D: Cosa succede se uso più branch o repository? R: La GitHub App monitora tutti i branch nei repository a cui concedi l’accesso. Puoi anche configurare quali repository vengono monitorati. Per più repository, ognuno riceve il proprio manifest e i propri file di prova.

D: Il mio codice sorgente viene mai esposto a Timestamp GIT? R: No. In modalità Standard, l’app legge solo l’hash del commit HEAD — mai il tuo codice sorgente. In modalità Enterprise ZK, una GitHub Action sulla tua infrastruttura invia solo l’hash del commit alla nostra API, quindi il tuo codice non lascia mai il tuo ambiente.

D: Quanto tempo ci vuole perché un commit venga timestampato? R: Gli hash dei commit vengono raggruppati e ancorati in Bitcoin una volta per notte. Dopo l’esecuzione notturna, occorrono tipicamente circa 3 ore perché la transazione Bitcoin venga confermata, dopodiché i file di prova .ots vengono respinti nel tuo repository.

Conclusione

Il timestamping manuale fallisce per lo stesso motivo per cui fallisce tutta la conformità manuale: dipende da un essere umano che si ricorda, ogni volta, per sempre. La GitHub App rimuove quella dipendenza. Installala una volta, e ogni commit su tutti i tuoi repository monitorati viene improntato, raggruppato, radicato in un Merkle tree e ancorato in Bitcoin secondo una pianificazione notturna — con badge, una dashboard pubblica di stato, un CSV di audit, certificati PDF e verifica locale nel browser a supporto.

Se lo stai valutando per un team, inizia con un singolo repository privato e osserva la prima settimana di heatmap riempirsi. Poi decidi fin dove estenderlo.

Installa la GitHub App, collega il tuo primo repo e lascia che il worker di mezzanotte faccia il resto.

Post correlati

Proteggere la proprietà intellettuale: una guida per sviluppatori software
Protezione della prior art per le startup software: una guida
GitHub Action per il timestamping dei commit: guida alla configurazione