Automatizza la marcatura temporale dei commit Git con una GitHub App

Se hai mai provato a dimostrare quando esisteva un commit Git, conosci già la procedura manuale: estrarre gli hash dei commit, creare un manifest, attendere le conferme, salvare i file di ricevuta in un posto sicuro e ripetere. È ripetitivo, facile da dimenticare e crolla nel momento in cui sono coinvolti più di un repository o più membri del team.

Esiste un modo migliore per automatizzare la marcatura temporale Bitcoin per i commit Git con una GitHub App. Timestamp GIT trasforma la prova di esistenza in un servizio in background: installa la GitHub App una volta, collega un repository e ogni commit viene ancorato alla blockchain Bitcoin ogni notte. Non devi eseguire strumenti di protocollo grezzi, ricordarti dei cron job o diventare un esperto di blockchain. Il flusso di lavoro OpenTimestamps grezzo esiste, ma farlo a mano è la strada difficile.

Questo articolo illustra il flusso di lavoro automatizzato, la configurazione una tantum, cosa succede tra il commit e l’ancoraggio Bitcoin e come monitorare e utilizzare le prove risultanti.

La fatica della marcatura temporale manuale che puoi eliminare

Il processo manuale per la marcatura temporale dei commit Git di solito funziona così:

1. Aspetti finché non ti ricordi che un commit avrebbe dovuto essere marcato temporalmente.
2. Estrai l’hash del commit da Git.
3. Prepari un file contenente gli hash che vuoi dimostrare esistessero.
4. Esegui uno strumento di marcatura temporale su quel file.
5. Attendi che la prova venga creata e confermata.
6. Salvi la ricevuta in un luogo duraturo.
7. Speri che nessuno ti chieda di spiegare i passaggi esatti in seguito.

Questo flusso di lavoro ha tre problemi seri.

Primo, gli sviluppatori dimenticano di marcare temporalmente. La prova di esistenza aiuta solo se la marcatura temporale è stata creata prima della controversia. Se te ne ricordi tre mesi dopo il fatto, la prova potrebbe essere più debole di quanto avrebbe potuto essere.

Secondo, le prove si perdono. Un file di ricevuta salvato su un laptop, un vecchio disco di backup o un canale casuale non è una traccia di audit. In un contesto legale o di conformità, le ricevute mancanti sembrano prove mancanti.

Terzo, i passaggi manuali non scalano. Uno sviluppatore singolo può occasionalmente marcare temporalmente un commit di rilascio. Una startup con 15 repository, più contributori e merge quotidiani non può affidarsi a qualcuno che esporta manualmente gli hash ogni sera.

Timestamp GIT automatizza l’intero protocollo OpenTimestamps dietro un servizio gestito. Il prodotto non legge il tuo codice sorgente. Raccoglie solo gli hash dei commit, li raggruppa in batch e crea prove crittografiche incorporate nella blockchain Bitcoin. Non tocchi mai una CLI, non costruisci mai un albero di Merkle e non sorvegli mai un processo di conferma.

Configurazione una tantum: collega il tuo repository

Il percorso di configurazione è progettato per essere eseguito una volta e poi dimenticato.

Inizi installando la Timestamp GIT GitHub App e selezionando i repository che vuoi monitorare. I repository pubblici possono essere coperti dal piano gratuito Open Source. I repository privati sono disponibili con i piani Pro Agency o Enterprise ZK.

Timestamp GIT offre due modalità di distribuzione.

Modalità Standard

In Modalità Standard, la GitHub App monitora il tuo repository tramite i webhook di GitHub. Quando appare un nuovo commit, l’app legge solo l’hash del commit HEAD.

I permessi GitHub richiedono accesso in sola lettura al repository sorgente perché GitHub non offre un ambito di accesso limitato al solo hash del commit. Timestamp GIT necessita anche di accesso in lettura-scrittura al repository di destinazione dove verranno scritte le prove. Il ramo delle prove può risiedere nello stesso repository o in un repository ombra separato.

La parte importante: il tuo codice sorgente non viene mai letto, copiato o archiviato. Solo gli hash dei commit entrano nella pipeline di Timestamp GIT.

Modalità Enterprise ZK

La Modalità Enterprise ZK è per i team che non possono concedere alcun accesso in lettura al repository a terze parti. Invece, una GitHub Action di 12 righe viene eseguita sulla tua infrastruttura e invia solo l’hash del commit all’API di Timestamp GIT.

In questa modalità, Timestamp GIT necessita di accesso in lettura-scrittura solo al repository di destinazione dove vengono archiviate le prove. Non necessita di accesso in lettura al repository sorgente. Il tuo codice sorgente non lascia mai il tuo ambiente.

Dopo la connessione iniziale, non ci sono passaggi manuali. Ogni commit su un repository monitorato viene rilevato automaticamente.

La pipeline automatizzata: dal commit all’ancoraggio Bitcoin

Una volta collegato un repository, la pipeline di automazione gestisce il resto.

La pipeline funziona così:

1. Rilevamento dei commit
   La GitHub App rileva i nuovi commit tramite webhook, oppure la tua GitHub Action invia gli hash dei commit all’API.

2. Coda degli hash
   Gli hash dei commit vengono archiviati in un archivio chiave-valore in memoria per il raggruppamento in batch.

3. Batch notturno
   Ogni notte, un worker raggruppa gli hash in sospeso e crea un file manifest .txt per ogni repository.

4. Albero di Merkle e OpenTimestamps
   Timestamp GIT costruisce nativamente un albero di Merkle, crea prove OpenTimestamps utilizzando calendari pubblici e ancora la radice di Merkle nella blockchain Bitcoin.

5. Consegna delle prove
   Il manifest e i file di ricevuta .ots vengono inviati a un ramo timestamps dedicato o a un repository ombra.

La conferma Bitcoin richiede in genere alcune ore, normalmente circa tre ore. Ciò significa che le prove sono solitamente disponibili il giorno successivo dopo l’invio del batch notturno.

Puoi controllare lo stato attuale di un repository tramite l’API pubblica:

curl -s https://timestampgit.dev/api/statusLast/acme/widget-api

curl -s https://timestampgit.dev/api/statusCount/acme/widget-api

curl -s https://timestampgit.dev/api/statusSummary/acme/widget-api

I repository privati aggiungono un HMAC crittografato a questi URL, così solo gli utenti autorizzati possono vedere lo stato. L’HMAC è specifico per l’istanza del server Timestamp GIT.

L’API espone anche endpoint di verifica e reportistica:

• GET /api/verify/{user}/{repo}/{date} restituisce i dati completi della catena di Merkle per la verifica locale di un giorno specifico.
• GET /api/audit/{user}/{repo} scarica il registro di audit completo in formato CSV.
• GET /api/report/{user}/{repo}/{date} scarica un certificato PDF per una data specifica.

L’endpoint di gestione dei repository, GET /api/repos/{user}, elenca i repository monitorati dopo l’installazione della GitHub App.

Per la Modalità Enterprise ZK, la procedura guidata di configurazione fornisce un URL firmato. La GitHub Action invia solo l’identificatore del commit a quell’URL. Il flusso di lavoro è intenzionalmente minimo, senza necessità di checkout del sorgente oltre al payload dell’evento già disponibile in GitHub Actions.

Monitoraggio e gestione dei guasti

L’automazione dovrebbe essere osservabile. Timestamp GIT fornisce una dashboard di stato pubblica per ogni repository.

La dashboard include:

• Longevità delle prove
• Data di ancoraggio più antica
• Regolarità giornaliera
• Dati di blocco e transazione Bitcoin
• Una heatmap di calendario
• CSV di audit scaricabile
• Download di certificati PDF

Puoi anche incorporare un badge di verifica nel tuo README. L’endpoint autenticato GET /api/badgeLink/{user}/{repo} restituisce gli URL dei badge e snippet Markdown pronti all’uso per Shields.io. Il badge mostra pubblicamente lo stato di verifica e si collega alla pagina di verifica.

Se la conferma Bitcoin richiede più tempo del previsto, la dashboard di stato mostra a che punto del processo si trova la prova. Poiché il sistema raggruppa in batch ogni notte, una conferma lenta di solito significa che la prova appare qualche ora più tardi del normale anziché sparire. Gli hash in coda rimangono nella pipeline e puoi controllare la pagina di stato per lo stato attuale.

La garanzia importante: la tua prova non dipende dalla disponibilità continua di Timestamp GIT. I file .ots sono archiviati nel tuo repository e la prova si basa solo su SHA-256 e sui dati dei blocchi Bitcoin. Puoi verificarla localmente anche se l’azienda scomparisse.

Buone pratiche per la marcatura temporale automatizzata

L’automazione elimina il peso manuale, ma alcune abitudini rendono le prove più solide.

Marca temporalmente ogni commit, non solo i rilasci.
I rilasci sono pietre miliari utili, ma una catena continua di hash dei commit crea un registro molto più ricco. Se una controversia riguarda un dettaglio di implementazione specifico, una marcatura temporale a livello di rilascio potrebbe essere troppo grossolana.

Usa un repository ombra dedicato per le prove.
Mantenere i file .ots e i file manifest in un repository di prove separato mantiene pulito il repository principale. Rende anche più semplice la raccolta degli audit perché tutti i dati delle prove vivono in un unico posto.

Considera il self-hosting Docker per ambienti air-gapped.
Timestamp GIT è disponibile come immagine Docker per i team che necessitano del massimo controllo. La configurazione quick-start è:

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 all’indirizzo http://localhost:8080 dopo l’avvio. Una procedura guidata di configurazione ti guida attraverso la connessione della tua GitHub App e la configurazione dell’istanza. Una licenza demo a tempo limitato è disponibile dalla pagina delle licenze Docker.

Scarica regolarmente i report di audit.
Tratta il registro di audit CSV e i certificati PDF come documenti legali. Archiviali insieme agli altri tuoi registri di protezione della proprietà intellettuale. Non aspettare che inizi una controversia per raccogliere le prove.

Combina la marcatura temporale con altre strategie di protezione della proprietà intellettuale.
La marcatura temporale non sostituisce brevetti, contratti o politiche sui segreti commerciali. È la prova crittografica che rende quelle altre strategie molto più difficili da contestare.

FAQ

La GitHub App ha bisogno di accedere al mio codice sorgente?

No. In Modalità Standard, la GitHub App legge solo l’hash del commit HEAD, non il codice stesso. In Modalità Enterprise ZK, una GitHub Action sulla tua infrastruttura invia solo l’hash del commit all’API, quindi il codice sorgente non lascia mai il tuo ambiente.

Quanto tempo ci vuole perché un commit venga marcato temporalmente?

I commit vengono raggruppati in batch ogni notte. Il processo di ancoraggio Bitcoin richiede in genere alcune ore dopo l’invio del batch, quindi le prove sono solitamente disponibili il giorno successivo. Puoi controllare la dashboard di stato per aggiornamenti in tempo reale.

Posso verificare la marcatura temporale senza fare affidamento su Timestamp GIT?

Sì. La prova è un file OpenTimestamps .ots standard che può essere verificato indipendentemente utilizzando strumenti pubblici e la blockchain Bitcoin. Timestamp GIT fornisce anche una pagina di verifica basata su browser e certificati PDF scaricabili.

Cosa succede se Timestamp GIT cessa l’attività?

Le tue prove rimangono valide perché sono ancorate nella blockchain Bitcoin e utilizzano solo standard aperti come SHA-256 e OpenTimestamps. Puoi verificarle offline in qualsiasi momento e i file .ots sono archiviati nel tuo repository.

Automatizza la prova, mantieni il controllo

La marcatura temporale manuale è facile da vendere internamente e difficile da sostenere nella pratica. Il valore della prova di esistenza deriva dalla coerenza: ogni commit, ogni giorno, senza ricevute mancanti.

Timestamp GIT trasforma tutto questo in un processo in background. Installa la GitHub App una volta, collega i tuoi repository e la pipeline notturna gestisce hash dei commit, alberi di Merkle, prove OpenTimestamps, ancoraggio Bitcoin e consegna delle prove. Monitori i risultati tramite dashboard, badge, audit CSV e certificati PDF.

I repository pubblici possono iniziare gratuitamente. I repository privati sono coperti da Pro Agency ed Enterprise ZK. Se hai bisogno di controllo air-gapped, la licenza Docker self-hosted mette la stessa automazione all’interno della tua infrastruttura.

Inizia con Timestamp GIT e rendi la prova di esistenza una parte normale del tuo flusso di lavoro sui commit.

Articoli correlati

• Alternativa a OpenTimestamps: marcatura temporale gestita per Git
• Protezione del codice per freelance: una soluzione di marcatura temporale
• Come Bitcoin può dimostrare che la tua proprietà intellettuale esisteva per prima