Installa una GitHub App per Timbrare Automaticamente i Tuoi Commit

Automatizzi già build, test, linting e deployment. Allora perché continui a timbrare manualmente i commit quando devi dimostrare la prior art? Il modo difficile è eseguire gli strumenti di protocollo commit per commit e tenere traccia dei file di prova da solo. Timestamp GIT lo sostituisce con una GitHub App gestita che timbra automaticamente ogni commit e lo ancora alla blockchain di Bitcoin.

Il flusso di lavoro è volutamente noioso dopo la configurazione: installa la GitHub App una sola volta, seleziona i repository che vuoi monitorare e lascia che la pipeline notturna crei le ricevute di prova .ots. Non c’è alcuna CLI da installare sulle macchine degli sviluppatori, nessun comando manuale da ricordare prima di un rilascio e nessun fragile archivio locale di timestamp.

Questo articolo copre la configurazione una tantum, cosa succede tra il commit e l’ancoraggio a Bitcoin, come monitorare le prove e le pratiche che mantengono le tue evidenze valide in tribunale.

Configurazione Una Tantum: Collega la GitHub App

L’automazione inizia con una singola installazione. Dopodiché, la GitHub App per la timestamping dei commit fa il lavoro ripetitivo al posto tuo.

1. Installa la GitHub App Timestamp GIT

Installa l’app sul tuo account personale o sulla tua organizzazione dalla dashboard di Timestamp GIT. Durante l’installazione, concedi l’accesso ai repository come per qualsiasi altra GitHub App.

In modalità standard, l’app richiede:

• Accesso in lettura al repository sorgente. GitHub non offre un permesso limitato al solo hash dei commit, quindi l’app ha bisogno almeno dell’accesso in sola lettura per rilevare gli hash dei commit.
• Accesso in scrittura al repository o branch di destinazione. I file di prova devono essere salvati da qualche parte. Può essere un branch dedicato timestamps nel repository sorgente o un repository shadow separato.

Anche con accesso in lettura, l’app legge solo l’hash del commit HEAD dei repository monitorati. Non legge file sorgente, diff, issue o contenuti delle pull request.

2. Seleziona i repository da monitorare

Dopo l’installazione, scegli i repository che devono ricevere la timestamping automatica. I repository pubblici sono disponibili nel piano gratuito. I repository privati richiedono un piano a pagamento Pro o Enterprise, a seconda delle tue esigenze di sicurezza e conformità.

Non ci sono modifiche al codice dell’applicazione. Non installi nulla sulle macchine degli sviluppatori e il tuo team non deve cambiare il proprio flusso di lavoro per i commit.

3. Scegli la consegna delle prove

Per impostazione predefinita, l’app crea un branch Git dedicato o un repository shadow per gli artefatti di prova. Questo mantiene le evidenze separate dalla storia principale del sorgente ed evita di inquinare le pull request con file .ots.

Modalità Enterprise ZK: accesso zero al codice

Se il tuo codice è proprietario, regolamentato o air-gapped, la modalità Enterprise ZK è l’opzione più rigorosa. 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à, l’app Timestamp GIT non ha bisogno di alcun accesso in lettura al tuo repository sorgente. Installi la GitHub Action e solo gli hash dei commit lasciano il tuo ambiente. Il tuo codice sorgente non lo fa mai.

Opzionale: modalità self-hosted con Docker

Per il massimo controllo, Timestamp GIT è disponibile anche come immagine Docker. È utile per ambienti air-gapped o organizzazioni che devono mantenere tutta l’infrastruttura on-premises.

Una configurazione Compose minima si presenta così:

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

Avviala con:

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

L’applicazione è disponibile su http://localhost:8080. Al primo avvio, una procedura guidata di configurazione ti guida attraverso la connessione della tua GitHub App e la configurazione dell’istanza.

La Pipeline Automatizzata: Dal Commit all’Ancoraggio a Bitcoin

Una volta installata la GitHub App, il processo di timestamping viene eseguito da solo.

Passo 1: Rilevamento dei commit

In modalità standard, la GitHub App rileva i nuovi commit tramite webhook. In modalità Enterprise ZK, la tua GitHub Action invia gli hash dei commit all’API come parte della CI/CD.

In entrambi i casi, l’unico dato che entra nella pipeline di Timestamp GIT è l’hash del commit.

Passo 2: Raggruppamento notturno e ancoraggio a Bitcoin

Gli hash dei commit vengono archiviati in un archivio chiave-valore in memoria per il raggruppamento. Ogni notte, un worker cron:

1. Raggruppa tutti gli hash dei commit in sospeso.
2. Crea un file manifest per ogni repository.
3. Costruisce un albero di Merkle dal batch giornaliero.
4. Crea le prove OpenTimestamps utilizzando calendari OTS pubblici.
5. Ancora la radice di Merkle nella blockchain di Bitcoin.

La radice di Merkle giornaliera è ciò che viene incorporato in Bitcoin. Una volta che la transazione viene confermata, l’hash è permanentemente congelato in uno specifico blocco di Bitcoin.

Passo 3: Consegna delle prove

Dopo che la transazione Bitcoin viene confermata, Timestamp GIT invia il manifest e i file di ricevuta .ots al branch timestamps dedicato o al repository shadow.

La conferma di Bitcoin richiede normalmente circa tre ore dopo l’invio del batch notturno. Ciò significa che un commit effettuato durante il giorno avrà tipicamente un file di prova disponibile entro il giorno successivo.

Passo 4: Stato e verifica

Puoi vedere la cronologia degli ancoraggi dalla dashboard di stato del repository. La dashboard pubblica mostra:

• Longevità delle prove
• Data del primo ancoraggio
• Regolarità dell’ancoraggio giornaliero
• Dati di blocco e transazione Bitcoin
• Una heatmap del calendario
• CSV di audit scaricabile e certificato PDF

Per l’accesso programmatico, sono disponibili endpoint di stato pubblici:

# Informazioni sull'ultimo blocco Bitcoin ancorato
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api

# Conteggio totale dei commit committati e timbrati
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api

# Riepilogo combinato per i badge Shields.io
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api

Il prodotto fornisce anche un endpoint badge autenticato per generare badge README con una singola richiesta. Per i repository privati, gli URL dei badge includono un HMAC crittografato in modo che solo gli utenti autorizzati possano vedere lo stato.

Monitoraggio e Gestione dei Guasti

Automazione non significa ignorare il sistema. Dovresti monitorare la regolarità degli ancoraggi allo stesso modo in cui monitori lo stato della CI.

La dashboard di stato è il posto più rapido per individuare un giorno mancante. Se un batch notturno non produce una prova, la data mancante sarà visibile come un vuoto nella heatmap del calendario e nella vista di regolarità giornaliera.

Per controlli programmatici, gli stessi endpoint sopra possono alimentare il tuo monitoraggio interno:

• Usa /api/statusLast/{user}/{repo} per confermare l’ancoraggio Bitcoin più recente.
• Usa /api/statusCount/{user}/{repo} per confrontare i commit timbrati con il conteggio dei commit previsto.
• Usa /api/audit/{user}/{repo} per scaricare il registro di audit completo come CSV.

Esempio:

# Scarica il registro di audit completo
curl -OJ https://timestampgit.dev/api/audit/acme/payments-api

# Scarica un certificato PDF per una data specifica
curl -OJ https://timestampgit.dev/api/report/acme/payments-api/2026-09-13

Poiché il sistema raggruppa gli hash a mezzanotte e la conferma di Bitcoin richiede circa tre ore, non considerare un commit appena inviato come completamente timbrato finché il file di prova non appare nel branch timestamps.

Infine, chiunque può verificare indipendentemente un file .ots contro la blockchain di Bitcoin. La prova si basa su ricevute OpenTimestamps standard e dati di blocco Bitcoin, quindi la verifica non dipende dalla disponibilità continua di Timestamp GIT.

Buone Pratiche per la Timestamping Automatizzata

1. Abilitala su tutti i repository critici

Timbrare solo i repository pubblici lascia il lavoro interno privato non protetto. I patent troll e le controversie con i dipendenti spesso coinvolgono sistemi proprietari che non lasciano mai la tua infrastruttura. Usa i piani per repository privati o la modalità Enterprise ZK per quelli.

2. Usa la modalità Enterprise ZK per i segreti commerciali

Se un repository contiene segreti commerciali o codice regolamentato, non concedere ad alcuna app di terze parti l’accesso in lettura. Usa la GitHub Action in modo che solo gli hash dei commit lascino il tuo ambiente.

3. Proteggi il branch timestamps

Le ricevute .ots e i file manifest sono le tue evidenze. Tratta il branch timestamps dedicato o il repository shadow come archivio di evidenze immutabile. Limita l’accesso in scrittura all’app e agli amministratori richiesti.

4. Archivia regolarmente i record di audit

Scarica i CSV di audit e i certificati PDF secondo una pianificazione, ad esempio trimestralmente o prima dei rilasci principali. Conserva le copie nel tuo archivio di conformità o legale. La prova blockchain esiste indipendentemente, ma avere la traccia di audit organizzata rende la revisione legale molto più semplice.

5. Aggiungi un badge di verifica al tuo README

I badge di verifica pubblici sono un modo semplice per segnalare che un repository ha la timestamping automatica abilitata. Usa il link del badge dalla dashboard o dall’API autenticata per incorporare un badge Shields.io nel tuo README.

FAQ

La GitHub App legge il mio codice sorgente?

No. In modalità standard, l’app legge solo l’hash del commit HEAD. In modalità Enterprise ZK, una GitHub Action dalla tua parte invia solo l’hash del commit all’API, quindi l’app non ha mai alcun accesso al tuo repository.

Quanto tempo ci vuole perché un commit venga timbrato?

I commit vengono raccolti durante il giorno e ancorati a Bitcoin in un batch notturno. Dopo l’invio del batch, la conferma di Bitcoin richiede tipicamente circa 3 ore. Ricevi il file di prova .ots una volta confermato.

Posso verificare il timestamp senza usare Timestamp GIT?

Sì. Le prove sono file OpenTimestamps .ots standard. Chiunque può scaricare il file e verificarlo localmente contro la blockchain di Bitcoin usando strumenti open-source. Timestamp GIT fornisce anche un verificatore web e certificati PDF.

È disponibile il self-hosting?

Sì. Timestamp GIT offre un’immagine Docker per il self-hosting, adatta ad ambienti air-gapped o altamente regolamentati. Una licenza demo a tempo limitato è disponibile su richiesta.

Conclusione: Configura e Dimentica

La timestamping manuale è fragile perché dipende dal fatto che qualcuno si ricordi di farla. Una pipeline basata su GitHub App elimina questa modalità di errore.

Con Timestamp GIT, installi una volta, selezioni i repository e lasci che il worker notturno ancori gli hash dei commit a Bitcoin. Il tuo team continua a scrivere codice normalmente. Le evidenze si accumulano automaticamente come file .ots, report di audit e badge di stato.

Installa la GitHub App Timestamp GIT oggi stesso, oppure inizia con il piano gratuito per i repository pubblici. I piani Pro ed Enterprise sono disponibili per repository privati e deployment zero-knowledge più rigorosi.

Post correlati

• Come le Startup Possono Proteggere la Propria IP Software Senza Brevetti
• Timestamping Git Open Source Gratuita con Timestamp GIT
• Cos’è la Timestamping Crittografica e Come Protegge il Tuo Codice?