--- title: "Connettore GitHub" description: "Guida completa all'integrazione di GitHub per sincronizzare eventi di repository, issue, pull request e attività degli sviluppatori con Brevo tramite Tajo." url: https://tajo.io/it/docs/connectors/custom/github/ markdown: https://tajo.io/it/docs/connectors/custom/github.md lang: it-IT robots: noindex --- Richiedi l’accesso anticipato Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo. # Connettore GitHub Stato del connettore: Pianificato Non ancora realizzato. Oggi Tajo non esegue questo connettore. | Campo di origine | Campo di destinazione | Valore di esempio | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Collega i tuoi repository GitHub a Brevo per monitorare l’engagement degli sviluppatori, attivare flussi di notifica sulle release e tracciare l’attività della community tramite Tajo. ## Panoramica | Proprietà | Valore | | --- | --- | | **Piattaforma** | GitHub | | **Categoria** | Custom | | **Complessità di setup** | Moderata | | **Integrazione ufficiale** | No | | **Dati sincronizzati** | Eventi, Utenti, Repository | | **Tipo di API** | REST API, GraphQL API | | **Autenticazione** | GitHub App / Personal Access Token / OAuth 2.0 | | **Base URL** | `https://api.github.com` | | **Versione API** | `2022-11-28` (versioning via header) | ## Funzionalità - **Tracciamento issue e PR** - Sincronizza eventi di issue e pull request sulle timeline dei contatti Brevo - **Notifiche di release** - Attiva campagne Brevo sulle nuove release dei repository - **Sync dei contributor** - Mappa i contributor GitHub sui contatti Brevo per la community engagement - **Tracciamento star e fork** - Monitora le metriche di popolarità dei repository - **Inoltro eventi webhook** - Inoltra gli eventi GitHub alle automazioni Brevo - **Catalogo repository** - Sincronizza i metadati dei repository come elementi del catalogo Brevo ## Prerequisiti Prima di iniziare, assicurati di avere: 1. Un account GitHub con accesso ai repository target 2. Una GitHub App o un Personal Access Token (fine-grained consigliato) 3. Accesso admin ai repository per la configurazione dei webhook 4. Un account Brevo con accesso API 5. Un account Tajo con abbonamento attivo ## Autenticazione GitHub supporta diversi metodi di autenticazione. Tajo consiglia l’uso di GitHub App per accessi a livello di organizzazione. ### Opzione 1: GitHub App (consigliata) 1. Vai su **Settings** > **Developer settings** > **GitHub Apps** 2. Clicca su **New GitHub App** 3. Configura l’app con questi permessi: ``` Repository permissions: Issues: Read Pull requests: Read Contents: Read Metadata: Read Organization permissions: Members: Read Subscribe to events: Issues Pull request Push Release Star Fork ``` ### Opzione 2: Fine-Grained Personal Access Token 1. Vai su **Settings** > **Developer settings** > **Personal access tokens** > **Fine-grained tokens** 2. Clicca su **Generate new token** 3. Seleziona i repository target 4. Concedi questi permessi: ``` Repository access: Selected repositories Permissions: Issues: Read-only Pull requests: Read-only Contents: Read-only Metadata: Read-only ``` Sicurezza dei token I token fine-grained hanno date di scadenza. Pianifica la rotazione dei token prima della scadenza. I token di installazione delle GitHub App si rinnovano automaticamente e sono preferibili in produzione. ### Connessione a Tajo ```bash # Usando GitHub App tajo connectors install github \ --app-id $GITHUB_APP_ID \ --private-key-path ./github-app-key.pem \ --installation-id $GITHUB_INSTALLATION_ID # Usando Personal Access Token tajo connectors install github \ --token $GITHUB_TOKEN ``` ## Configurazione ### Setup di base ```yaml connectors: github: enabled: true auth_type: "github_app" # oppure "token" repositories: - owner/repo-1 - owner/repo-2 sync: issues: true pull_requests: true releases: true contributors: true stars: true lists: contributors: 20 stargazers: 21 ``` ### Mapping dei campi Mappa i dati utente GitHub sugli attributi dei contatti Brevo: ```yaml field_mapping: # Campi standard login: GITHUB_USERNAME email: email name: FIRSTNAME # Metriche dello sviluppatore contributions: GITHUB_CONTRIBUTIONS repositories_count: GITHUB_REPOS followers: GITHUB_FOLLOWERS created_at: GITHUB_JOINED # Attributi personalizzati company: COMPANY location: LOCATION bio: GITHUB_BIO ``` ## Endpoint API Tajo si integra con i seguenti endpoint della REST API di GitHub: | Endpoint | Metodo | Scopo | | --- | --- | --- | | `/repos/{owner}/{repo}/issues` | GET | Elenca le issue del repository | | `/repos/{owner}/{repo}/pulls` | GET | Elenca le pull request | | `/repos/{owner}/{repo}/releases` | GET | Elenca le release | | `/repos/{owner}/{repo}/contributors` | GET | Elenca i contributor | | `/repos/{owner}/{repo}/stargazers` | GET | Elenca gli stargazer | | `/repos/{owner}/{repo}/forks` | GET | Elenca i fork | | `/repos/{owner}/{repo}/events` | GET | Elenca gli eventi del repository | | `/users/{username}` | GET | Ottieni il profilo utente | | `/orgs/{org}/members` | GET | Elenca i membri dell’organizzazione | | `/repos/{owner}/{repo}/hooks` | POST | Crea un webhook | ## Esempi di codice ### Inizializzare il connettore ```javascript import { TajoClient } from '@tajo/sdk'; const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY }); await tajo.connectors.connect('github', { appId: process.env.GITHUB_APP_ID, privateKey: process.env.GITHUB_PRIVATE_KEY, installationId: process.env.GITHUB_INSTALLATION_ID }); ``` ### Sincronizzare i contributor su Brevo ```javascript await tajo.connectors.sync('github', { type: 'full', resources: ['contributors'], repositories: ['owner/repo-1', 'owner/repo-2'] }); const status = await tajo.connectors.status('github'); console.log(status); // { // connected: true, // lastSync: '2024-03-15T11:00:00Z', // contributorsCount: 245, // issuesTracked: 1890, // releasesTracked: 34 // } ``` ### Gestire gli eventi webhook ```javascript app.post('/webhooks/github', async (req, res) => { const signature = req.get('X-Hub-Signature-256'); const event = req.get('X-GitHub-Event'); // Verifica la firma del webhook if (!verifyGitHubSignature(req.body, signature)) { return res.status(401).send('Unauthorized'); } await tajo.connectors.handleWebhook('github', { event, payload: req.body }); res.status(200).send('OK'); }); ``` ### Attivare una campagna sulle release ```javascript // Ascolta le nuove release e attiva una campagna Brevo tajo.connectors.on('github', 'release.published', async (event) => { await tajo.campaigns.trigger('release-announcement', { listId: 21, params: { version: event.release.tag_name, release_notes: event.release.body, download_url: event.release.html_url } }); }); ``` ## Limiti di rate GitHub applica limiti di rate in base al metodo di autenticazione: | Autenticazione | Rate limit primario | Search API | | --- | --- | --- | | **Non autenticata** | 60 richieste/ora | 10 richieste/minuto | | **Personal Access Token** | 5.000 richieste/ora | 30 richieste/minuto | | **GitHub App (installation)** | 5.000 richieste/ora | 30 richieste/minuto | | **GitHub App (user-to-server)** | 5.000 richieste/ora | 30 richieste/minuto | Richieste condizionali Tajo usa richieste condizionali (header `If-None-Match` / `If-Modified-Since`) per ridurre il consumo di API. Le risposte con `304 Not Modified` non vengono conteggiate contro il rate limit. Limiti aggiuntivi: - **Rate limit secondari**: non più di 100 richieste concorrenti. Non più di 900 punti al minuto per gli endpoint REST API. - **GraphQL**: 5.000 punti all’ora (il costo della query varia in base alla complessità). ## Risoluzione dei problemi ### Problemi comuni | Problema | Causa | Soluzione | | --- | --- | --- | | 401 Unauthorized | Token scaduto o credenziali errate | Rigenera il token o reinstalla la GitHub App | | 403 Forbidden | Permessi insufficienti | Controlla gli scope del token o i permessi dell’App | | 404 Not Found | Repo privato senza accesso | Concedi l’accesso al repository al token o all’App | | Rate limit superato | Troppe chiamate API | Abilita le richieste condizionali e riduci la frequenza di sync | | Webhook non ricevuti | URL errato o firewall | Verifica che l’URL del webhook sia accessibile pubblicamente | ### Modalità debug ```yaml connectors: github: debug: true log_level: verbose log_webhooks: true ``` ### Testare la connessione ```bash tajo connectors test github # ✓ Autenticazione API riuscita # ✓ Accesso ai repository verificato # ✓ Dati issue leggibili # ✓ Consegna webhook attiva # ✓ Rate limit sano (4.850/5.000 rimanenti) ``` ## Best practice 1. **Preferisci le GitHub App ai PAT** - Le GitHub App offrono permessi granulari e token auto-refreshing 2. **Abilita i segreti dei webhook** - Verifica sempre le firme webhook con HMAC-SHA256 3. **Usa richieste condizionali** - Sfrutta gli ETag per non sprecare quota del rate limit 4. **Paginate le risposte grandi** - GitHub restituisce max 100 elementi per pagina; itera tramite header `Link` 5. **Sincronizza nei momenti di minore attività** - Pianifica i sync completi fuori dagli orari di picco 6. **Monitora gli header di rate limit** - Controlla `X-RateLimit-Remaining` per applicare throttling in modo proattivo ## Sicurezza - **Autenticazione GitHub App** - JWT basato su chiave RSA con token di installazione a breve durata - **Firme webhook** - Verifica firma HMAC-SHA256 su tutti i payload webhook - **Token fine-grained** - Limitati a repository e permessi specifici - **Solo HTTPS** - Tutte le comunicazioni API cifrate tramite TLS 1.2+ - **Archiviazione cifrata** - Chiavi private e token cifrati a riposo in Tajo - **Scadenza token** - I token fine-grained scadono automaticamente; imposta alert di rotazione ## Risorse correlate - [Connettore Jira](https://tajo.io/it/docs/connectors/custom/jira) - [Connettore Linear](https://tajo.io/it/docs/connectors/custom/linear) - [Connettore Notion](https://tajo.io/it/docs/connectors/custom/notion) - [Brevo Contacts API](https://tajo.io/it/docs/contact-management)