Timestamp automatico per ogni commit Git con una GitHub App

2026-08-31 timestamp git blockchain proof

Applica automaticamente un timestamp a ogni commit Git con una GitHub App

Ogni volta che esegui un commit, Git genera già un hash univoco che identifica lo stato esatto del tuo repository. Quell’hash è un’impronta digitale crittograficamente sicura del tuo lavoro in quel momento. Ciò che non è, di per sé, è la prova di quando quel lavoro è esistito. Trasformare quell’hash in una prova immutabile, pronta per un tribunale, un tempo significava un processo manuale: eseguire comandi aggiuntivi, sorvegliare l’output, archiviare i file di ricevuta e ripetere tutto per ogni commit.

L’alternativa automatizzata è più semplice: installa una GitHub App una sola volta, seleziona i tuoi repository e lascia che ogni commit futuro venga ancorato alla blockchain di Bitcoin mentre dormi.

Timestamp GIT è un servizio gestito costruito attorno a questa idea. Automatizza completamente il protocollo OpenTimestamps, così non devi mai toccare una CLI, costruire una transazione Bitcoin o gestire manualmente i file di prova. Questo articolo copre la configurazione una tantum, la pipeline di automazione notturna, il monitoraggio, le best practice e le domande più comuni.

Configurazione una tantum: installa la GitHub App Timestamp GIT

L’intero prodotto è progettato attorno a un unico flusso di configurazione. Dopodiché, eseguire il commit del codice è l’unica azione che devi compiere.

Modalità Standard: GitHub App

Installa la Timestamp GIT GitHub App dal GitHub Marketplace.
Concedi i permessi richiesti durante l’installazione. In Modalità Standard, l’app richiede accesso in sola lettura al repository sorgente perché i permessi di GitHub non offrono uno scope limitato ai soli hash dei commit. Timestamp GIT non legge, copia o archivia mai il tuo codice sorgente.
Seleziona i repository che vuoi monitorare. I repository pubblici sono supportati nel piano gratuito Open Source; i repository privati richiedono un piano a pagamento.
Scegli dove devono risiedere i file di prova. Puoi archiviarli in un branch dedicato timestamps nello stesso repository, oppure in un repository di destinazione separato. Un repository ombra separato mantiene pulita la cronologia del sorgente principale.

Dopo l’installazione, la GitHub App monitora automaticamente i repository selezionati. Non ci sono strumenti CLI da installare, nessun comando OpenTimestamps da imparare e nessun passaggio manuale da eseguire dopo la configurazione.

Modalità Enterprise ZK: GitHub Action

Per le organizzazioni che desiderano il massimo isolamento, Timestamp GIT offre una Modalità Enterprise ZK. Invece di concedere alla GitHub App accesso in lettura al repository sorgente, una GitHub Action viene eseguita sulla tua infrastruttura e invia solo l’hash del commit all’API di Timestamp GIT.

La struttura del workflow si presenta così:

name: timestamp-git-zk

on:
  push:

jobs:
  timestamp:
    runs-on: ubuntu-latest
    steps:
      - name: Push commit hash to Timestamp GIT
        env:
          COMMIT_SHA: ${{ github.sha }}
          REPO: ${{ github.repository }}
        run: |
          curl -fsS -X POST \
            -H "Authorization: Bearer ${{ secrets.TIMESTAMP_GIT_HMAC }}" \
            -H "Content-Type: application/json" \
            -d "{\"repo\":\"$REPO\",\"hash\":\"$COMMIT_SHA\"}" \
            "${{ vars.TIMESTAMP_GIT_API_URL }}"

L’URL esatto dell’API, gli identificatori del repository e il segreto HMAC vengono forniti durante la procedura guidata di configurazione Enterprise. La parte importante è ciò che il workflow non fa: non invia mai codice sorgente, file o contenuti del repository. Invia un hash del commit e nient’altro.

In questa modalità, Timestamp GIT non ha bisogno di alcun accesso in lettura al tuo repository sorgente.

La pipeline automatizzata: dal commit all’ancoraggio su Bitcoin

Una volta che la GitHub App o la GitHub Action è operativa, l’applicazione del timestamp diventa un processo in background.

1. Rilevamento dei commit

In Modalità Standard, la GitHub App riceve webhook quando nuovi commit arrivano nei repository monitorati. In Modalità Enterprise ZK, la tua GitHub Action invia l’hash del commit direttamente all’API.

2. Coda degli hash

Gli hash dei commit rilevati entrano in un archivio chiave-valore in memoria dove attendono l’elaborazione in batch. Timestamp GIT non analizza il tuo codice, non clona l’intero repository e non ispeziona il contenuto dei file.

3. Worker cron notturno

Ogni notte, un worker raggruppa tutti gli hash in sospeso per repository. Per ogni repository, crea un file manifest, costruisce un albero di Merkle in modo nativo e crea le prove OpenTimestamps utilizzando calendari OTS pubblici.

4. Ancoraggio su Bitcoin

La radice di Merkle del batch giornaliero viene incorporata in una transazione Bitcoin utilizzando il protocollo OpenTimestamps. Una volta che la transazione è confermata in un blocco Bitcoin, l’ancora diventa immutabile. Nessuna entità, incluso Timestamp GIT, può alterarla o falsificarla.

La conferma su Bitcoin richiede normalmente circa tre ore. Ciò significa che un commit effettuato durante la giornata lavorativa è tipicamente ancorato entro la mattina successiva.

5. Consegna delle prove

Dopo la conferma, il manifest e i file di ricevuta .ots vengono inviati alla posizione di prova configurata: un branch timestamps dedicato oppure un repository ombra. I file di prova sono piccoli file di testo e binari che dimostrano che l’hash del tuo commit esisteva prima che il blocco Bitcoin venisse minato.

Puoi interrogare l’ultimo blocco ancorato per un repository pubblico con una semplice chiamata API:

curl -s https://timestampgit.dev/api/statusLast/your-org/your-repo

La risposta contiene le informazioni sull’ultimo blocco Bitcoin ancorato. Endpoint aggiuntivi restituiscono il conteggio totale dei commit marcati, riepiloghi di stato combinati e i dati completi della catena di Merkle per un giorno specifico.

Monitoraggio e gestione dei fallimenti

L’automazione è utile solo quando puoi verificare che stia funzionando.

Dashboard dello stato del repository

Ogni repository connesso riceve una pagina di stato pubblica o autenticata. La dashboard mostra:

Longevità delle prove: quanto indietro arriva la tua data di ancoraggio più remota
Regolarità giornaliera: se i commit vengono raggruppati in modo coerente
Dati del blocco Bitcoin e della transazione per ogni ancora
Una heatmap del calendario per una vista visiva dell’attività

La pagina di stato ti dà una risposta rapida alla domanda: “I commit di ieri sono stati ancorati?”

Esportazioni per audit e conformità

Timestamp GIT fornisce registri di audit scaricabili:

# Scarica un registro di audit completo in formato CSV
curl -o audit.csv https://timestampgit.dev/api/audit/your-org/your-repo

Puoi anche scaricare un certificato PDF per una data specifica. Queste esportazioni sono utili per archivi di conformità, revisioni legali o documentazione IP a livello dirigenziale.

Gestione dei commit mancati

Nel funzionamento normale, un commit che perde il batch notturno, ad esempio perché la consegna di un webhook è stata ritardata, viene ripreso nel successivo ciclo notturno. Il design orientato ai batch significa che i fallimenti temporanei non richiedono di rieseguire nulla manualmente.

Privacy dei repository privati

Per i repository privati, gli endpoint di stato sono protetti con un HMAC crittografato. Solo gli utenti autorizzati con la corretta firma URL possono visualizzare lo stato del repository. L’HMAC è specifico per l’istanza del server, quindi i dati di stato non sono esposti al pubblico.

Best practice per l’applicazione automatica dei timestamp

Una GitHub App può automatizzare la meccanica, ma alcune scelte di configurazione rendono le prove più solide e più facili da gestire.

Monitora tutti i repository attivi

Non monitorare solo i branch di release. Le controversie sullo stato dell’arte spesso ruotano attorno a un commit sperimentale iniziale, un branch work-in-progress o un rapido prototipo. Abilita il monitoraggio su ogni repository in cui viene scritto codice significativo.

Usa un repository ombra dedicato

Se non vuoi che i file di prova ingombrino il repository principale, configura Timestamp GIT per inviare le prove a un repository separato. Questo mantiene pulita la cronologia del sorgente, offrendo comunque ad avvocati, revisori e team di conformità un unico posto in cui cercare le ricevute di prova.

Scegli la Modalità Enterprise ZK per il massimo isolamento

Se il tuo codice è altamente sensibile o la tua politica di sicurezza vieta l’accesso in lettura di terze parti ai repository sorgente, usa la Modalità Enterprise ZK. L’approccio con GitHub Action significa che il tuo codice sorgente non lascia mai il tuo ambiente. Timestamp GIT riceve esclusivamente gli hash dei commit.

Archivia regolarmente i CSV di audit

I file .ots sono la prova crittografica, ma i CSV di audit sono il registro leggibile dall’uomo. Scaricali secondo una pianificazione e archiviali insieme agli altri documenti di conformità. In una controversia, avere un registro cronologico pulito fa risparmiare tempo.

Aggiungi badge di verifica al tuo README

I repository pubblici possono mostrare un badge di verifica che rimanda alla pagina di stato di Timestamp GIT. La pagina di connessione del repository fornisce gli URL dei badge e gli snippet Markdown. Un badge tipico si presenta così:

[![Timestamp GIT verification](https://timestampgit.dev/api/badgeLink/your-org/your-repo)](https://timestampgit.dev/status/your-org/your-repo)

Chiunque visualizzi il repository può fare clic e verificare lo stato attuale del timestamp senza installare nulla.

FAQ

Come fa la GitHub App ad applicare automaticamente i timestamp ai miei commit?

Una volta installata, la GitHub App monitora i repository selezionati. Ogni notte raccoglie tutti i nuovi hash dei commit, crea un albero di Merkle, ancora la radice nella blockchain di Bitcoin tramite OpenTimestamps e invia i file di prova .ots al tuo repository. Non sono richiesti passaggi manuali.

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

In Modalità Standard, la GitHub App richiede accesso in sola lettura al repository sorgente per leggere gli hash dei commit, perché i permessi di GitHub richiedono quello scope. Tuttavia, Timestamp GIT non legge, copia o archivia mai il tuo codice sorgente: elabora solo l’hash del commit. In Modalità Enterprise ZK, una GitHub Action viene eseguita sulla tua infrastruttura e invia solo l’hash del commit all’API, quindi l’app non ha alcun accesso al tuo repository sorgente.

Quanto tempo serve perché un commit venga marcato con timestamp su Bitcoin?

I commit vengono raggruppati ogni notte. Dopo l’elaborazione del batch, la transazione Bitcoin viene trasmessa. La conferma sulla blockchain di Bitcoin richiede tipicamente circa tre ore, dopodiché i file di prova vengono scritti nel tuo repository. Un commit effettuato durante il giorno avrà di solito la sua prova di timestamp disponibile entro la mattina successiva.

Posso verificare il timestamp senza dipendere da Timestamp GIT?

Sì. La prova è un file OpenTimestamps .ots standard. Puoi scaricarlo e verificarlo localmente utilizzando qualsiasi strumento di verifica OpenTimestamps contro la blockchain di Bitcoin. Timestamp GIT fornisce anche una pagina di verifica web e certificati PDF per comodità.

Conclusione: configura e dimentica

Timestamp GIT trasforma la protezione crittografica dello stato dell’arte da un’attività manuale noiosa a un processo automatico in background. Installa la GitHub App una volta, seleziona i tuoi repository e ogni commit futuro fluirà attraverso la stessa pipeline: rilevamento dell’hash, raggruppamento notturno, costruzione dell’albero di Merkle, ancoraggio su Bitcoin e consegna delle prove.

Il modello di sicurezza è intenzionalmente zero-knowledge. Il tuo codice sorgente non viene mai letto né archiviato. La Modalità Standard elabora solo gli hash dei commit, e la Modalità Enterprise ZK mantiene persino quegli hash sotto il tuo controllo finché non li invii all’API.

I prezzi coprono i casi più comuni: Open Source è gratuito per i repository pubblici, Pro Agency costa $49/mese per i repository privati, ed Enterprise ZK costa $199/mese con supporto GitHub Actions. Per ambienti air-gapped o autogestiti, è disponibile anche una licenza Docker self-hosted.

Se stai ancora creando manualmente i timestamp per i singoli commit, il percorso più rapido è installare la Timestamp GIT GitHub App o richiedere una licenza Docker self-hosted per il massimo controllo.

Timestamp automatico per ogni commit Git con una GitHub App