Installa una GitHub App per la Timbratura Automatica del Codice

2026-08-18 timestamp git blockchain proof

Installa una GitHub App per la marcatura temporale automatica del codice

Vuoi installare una GitHub app per la marcatura temporale del codice, così che ogni commit che fai venga automaticamente ancorato alla blockchain di Bitcoin, senza mantenere script, eseguire cron job o occuparti personalmente di OpenTimestamps. È esattamente ciò che fa Timestamp GIT: installi la GitHub App una sola volta, selezioni quali repository proteggere e ogni commit viene sottoposto a hashing, raggruppato in batch e ancorato a Bitcoin ogni notte. Nessun passaggio manuale dopo la configurazione.

Questa guida è operativa. Sei pronto a implementare, non solo a valutare. Alla fine, avrai installato la GitHub App Timestamp GIT, collegato il tuo primo repository e predisposto un badge di verifica o una traccia di audit.

Potresti eseguire OpenTimestamps manualmente, creare transazioni Bitcoin a mano e sorvegliare i cron job: la via difficile. Oppure puoi installare una GitHub App gestita e lasciare che Timestamp GIT nasconda l’intero protocollo dietro un flusso di lavoro a configurazione zero. Questo articolo illustra il primo percorso.

Prerequisiti per l’installazione della GitHub App Timestamp GIT

Prima di iniziare, assicurati di avere:

Diritti di amministratore su GitHub per il repository o l’organizzazione che vuoi proteggere. Ti serve il permesso di installare una GitHub App e di concedere l’accesso ai repository.
Un account Timestamp GIT su timestampgit.dev. Registrati con la tua identità GitHub.
Una comprensione delle due modalità di implementazione:
- Modalità Standard (GitHub App): l’app legge automaticamente l’hash del commit HEAD dei repository monitorati. Richiede accesso in sola lettura al repository sorgente perché GitHub non offre permessi limitati al solo hash del commit. Richiede inoltre accesso in lettura-scrittura al repository di destinazione in cui verranno archiviate le prove.
- Modalità Enterprise ZK (GitHub Action): una GitHub Action di 12 righe viene eseguita sulla tua infrastruttura e invia solo gli hash dei commit all’API di Timestamp GIT. L’app non ha alcun accesso al tuo repository sorgente. Ti serve solo l’accesso in lettura-scrittura al repository di destinazione.
Un piano a pagamento se vuoi marcare temporalmente repository privati. Il piano gratuito Open Source copre i repository pubblici. I repository privati richiedono Pro Agency ($49/mese) o Enterprise ZK ($199/mese). Le pagine di stato e i badge privati sono protetti con un token HMAC crittografato.
Nessuno strumento locale o utility CLI. Tutto è gestito tramite l’app web Timestamp GIT e la GitHub App. Non installi nulla sulle tue macchine di sviluppo.

Passo dopo passo: installa e configura la GitHub App

Passo 1: accedi a Timestamp GIT e apri la pagina di installazione della GitHub App

Accedi su timestampgit.dev. Una volta effettuato l’accesso, vai alla pagina di configurazione dei repository, di solito Your Repositories nella dashboard. Clicca sull’opzione per installare la GitHub App.

Passo 2: autorizza Timestamp GIT sul tuo account GitHub o sulla tua organizzazione

Clicca su Install GitHub App. GitHub ti chiederà di scegliere tra il tuo account personale e le organizzazioni che amministri. Seleziona l’account proprietario dei repository che vuoi proteggere.

Passo 3: seleziona i repository e imposta i permessi sorgente

Scegli quali repository Timestamp GIT deve monitorare.

In Modalità Standard, concedi accesso in sola lettura ai repository sorgente. La GitHub App ha bisogno di questo permesso perché GitHub non fornisce un permesso limitato al solo hash del commit. Timestamp GIT estrae esclusivamente l’hash del commit; non legge né archivia mai il tuo codice sorgente.
In Modalità Enterprise ZK, non concedere alcun accesso al repository sorgente. La GitHub Action viene eseguita nella tua pipeline CI e invia solo hash all’API, quindi l’app non tocca mai il tuo codice.

Passo 4: scegli dove verranno archiviate le prove di marcatura temporale

Seleziona il repository di destinazione. Può essere lo stesso repository del tuo codice sorgente oppure un repository ombra separato. Timestamp GIT invierà i file manifest e le ricevute .ots a un ramo dedicato denominato timestamps nel repository di destinazione.

Per la Modalità Standard, il repository di destinazione richiede accesso in lettura-scrittura. Per la Modalità Enterprise ZK, ti serve l’accesso in lettura-scrittura solo al repository di destinazione.

Passo 5: per la Modalità Enterprise ZK, aggiungi il workflow della GitHub Action

Se hai scelto la Modalità Enterprise ZK, la dashboard di Timestamp GIT genera per te uno snippet YAML di 12 righe. Copialo in un file di workflow nel tuo repository sorgente, ad esempio .github/workflows/timestampgit.yml.

Un workflow generato è simile a questo (usa lo snippet esatto della tua dashboard):

# Enterprise ZK Mode workflow generated by Timestamp GIT.
# This runs on your infrastructure and sends only commit hashes.
name: timestamp-git-zk
on:
  push:
    branches: [main]
jobs:
  send-hash:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Send commit hash to Timestamp GIT
        env:
          TIMESTAMPGIT_HMAC: ${{ secrets.TIMESTAMPGIT_HMAC }}
        run: |
          # The exact command is generated by Timestamp GIT.
          # It pushes the HEAD commit hash to the API endpoint.

L’action invia solo l’hash del commit. Il tuo codice sorgente non lascia mai il tuo ambiente.

Passo 6: conferma la configurazione nella dashboard di Timestamp GIT

Torna su Timestamp GIT e conferma l’installazione. In Modalità Standard, la GitHub App inizierà a rilevare i commit automaticamente tramite i webhook di GitHub. In Modalità Enterprise ZK, l’Action invierà gli hash dei commit all’API a ogni push.

A questo punto dovresti vedere il tuo repository elencato in Your Repositories con uno stato che indica che è collegato.

Passo 7: aggiungi un badge di verifica al tuo README

Dalla pagina del repository collegato (https://timestampgit.dev/connected/{user}/{repo}), copia lo snippet markdown per un badge Shields.io. Ha questo aspetto, con i tuoi nomi utente e repository reali:

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

Incollalo nel tuo README.md. I visitatori pubblici possono cliccare sul badge per visualizzare lo stato di verifica pubblico del tuo repository.

Come confermare che la marcatura temporale funzioni

Dopo l’installazione, attendi il batch notturno e la conferma su Bitcoin. Ecco come verificare che i tuoi primi commit siano stati ancorati correttamente.

Controlla la pagina di stato del repository. Apri https://timestampgit.dev/status/{user}/{repo}. Mostra la data di ancoraggio più antica, la regolarità giornaliera, i dati di blocco e transazione Bitcoin e una mappa di calore del calendario dei commit marcati.
Cerca il ramo timestamps. Nel tuo repository di destinazione, trova il ramo dedicato timestamps (o il repository ombra). Contiene i file manifest e i file di ricevuta .ots per ogni batch giornaliero.
Esegui la verifica locale nel browser. Visita https://timestampgit.dev/verification/{user}/{repo}/{date}. La pagina esegue una verifica passo dopo passo della catena di Merkle localmente nel tuo browser, a conoscenza zero: nessuno vede cosa verifichi. Non devi installare nulla.
Scarica i record di conformità. Usa gli endpoint CSV di audit e certificato PDF. Ad esempio:
- https://timestampgit.dev/api/audit/{user}/{repo} scarica il registro di audit completo in formato CSV.
- https://timestampgit.dev/api/report/{user}/{repo}/{date} scarica un certificato PDF per un giorno specifico.
Ricorda i tempi. I commit vengono raggruppati in batch ogni notte da un worker cron. La radice di Merkle viene poi ancorata in una transazione Bitcoin. La conferma su Bitcoin richiede normalmente circa 3 ore, quindi le prove sono di solito disponibili il giorno successivo. Se non vedi una prova immediatamente dopo un commit, è previsto.

Risoluzione dei problemi comuni di installazione

Problema: nessun commit viene marcato temporalmente.
Controlla che la GitHub App abbia i permessi corretti e che il repository sia selezionato nella dashboard di Timestamp GIT. In Modalità Standard, l’app ha bisogno di accesso in sola lettura al repository sorgente e in lettura-scrittura al repository di destinazione. In Modalità Enterprise ZK, la GitHub Action deve essere installata nel repository sorgente e configurata per inviare dati all’API.

Problema: le prove non compaiono dopo un giorno.
Verifica che il worker cron notturno sia stato eseguito e che la transazione Bitcoin sia stata confermata. La conferma su Bitcoin richiede di solito circa 3 ore dopo l’elaborazione del batch. Controlla la pagina di stato del repository per le informazioni sull’ultimo blocco ancorato. Se sono trascorse più di 24 ore, verifica che il repository di destinazione abbia un ramo timestamps e che la GitHub App disponga ancora dell’accesso in scrittura.

Problema: lo stato del repository privato non è visibile.
Le pagine di stato e i badge dei repository privati sono protetti con un token HMAC crittografato. Assicurati di usare l’URL autenticato che contiene il valore HMAC. Verifica inoltre di avere un piano a pagamento (Pro Agency o Enterprise ZK). Il piano gratuito Open Source non copre i repository privati.

Problema: la Modalità Enterprise ZK non invia gli hash.
Verifica che il file di workflow della GitHub Action sia presente in .github/workflows/ e che il segreto TIMESTAMPGIT_HMAC sia impostato correttamente nelle impostazioni del repository. Controlla i log di esecuzione del workflow in GitHub Actions per confermare che l’endpoint API sia raggiungibile e che l’action sia stata completata con successo.

Problema: la verifica fallisce localmente sulla pagina di verifica pubblica o con un file .ots scaricato.
Assicurati di usare il file .ots corretto per la data specifica. Verifica inoltre che i tuoi strumenti OpenTimestamps locali siano aggiornati se stai verificando fuori dal browser. La pagina di verifica stessa esegue tutti i calcoli localmente e dovrebbe funzionare con qualsiasi browser moderno.

FAQ

La GitHub App Timestamp GIT ha accesso al mio codice sorgente?

In modalità Standard, la GitHub App richiede accesso in sola lettura al repository sorgente perché GitHub non fornisce permessi limitati al solo hash del commit. Tuttavia, Timestamp GIT estrae esclusivamente l’hash del commit e non legge né archivia mai il tuo codice sorgente. In modalità Enterprise ZK, la 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 ci vuole perché un commit venga marcato temporalmente sulla blockchain di Bitcoin?

I commit vengono raggruppati in batch ogni notte. Dopo l’elaborazione del batch, la radice di Merkle viene ancorata in una transazione Bitcoin. La conferma su Bitcoin richiede in genere circa 3 ore, quindi la prova è di solito disponibile il giorno successivo. Puoi monitorare lo stato nella dashboard del tuo repository.

Posso usare Timestamp GIT per repository privati?

Sì, i repository privati sono supportati sui piani Pro Agency ($49/mese) ed Enterprise ZK ($199/mese). Il piano gratuito Open Source è limitato ai repository pubblici. Le pagine di stato e i badge dei repository privati sono protetti con un token HMAC crittografato.

Cosa succede se Timestamp GIT cessa l’attività? Posso ancora verificare le mie marcature temporali?

Le tue prove sono archiviate come file .ots nel tuo repository e ancorate nella blockchain di Bitcoin. Puoi verificarle in modo indipendente usando gli strumenti OpenTimestamps standard e i dati dei blocchi Bitcoin. Non è richiesta alcuna tecnologia proprietaria, quindi le tue prove restano valide anche senza Timestamp GIT.

Conclusione: inizia a proteggere il tuo codice oggi

L’installazione della GitHub App Timestamp GIT richiede pochi minuti. Dopodiché, ogni commit su un repository monitorato viene sottoposto a fingerprinting, raggruppato in batch e ancorato automaticamente alla blockchain di Bitcoin. Ottieni prove pronte per il tribunale, verifiche indipendenti dal fornitore e zero impegno continuativo.

Se hai bisogno della massima sicurezza in un ambiente air-gapped o self-hosted, Timestamp GIT è disponibile anche come immagine Docker con una licenza demo a tempo limitato. Ma per la maggior parte dei team, la GitHub App gestita è il percorso più rapido verso la prior art crittografica.

Inizia su Timestamp GIT, registrati, installa la GitHub App e collega oggi il tuo primo repository.