--- title: "Conector de GitHub" description: "Guía completa de integración con GitHub para sincronizar eventos de repositorios, issues, pull requests y actividad de desarrolladores con Brevo a través de Tajo." url: https://tajo.io/es/docs/connectors/custom/github/ markdown: https://tajo.io/es/docs/connectors/custom/github.md lang: es-ES robots: noindex --- Solicita acceso anticipado Escribe tu nombre y dirección de correo de trabajo. Te enviaremos un enlace para confirmar tu solicitud de acceso a Tajo. # Conector de GitHub Estado del conector: Planificado Aún no está construido. Tajo no ejecuta este conector hoy. | Campo de origen | Campo de destino | Valor de ejemplo | | --- | --- | --- | | `record.id` | `source_id` | `record_1042` | | `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` | | `record.value` | `value` | `sample_value` | Conecta tus repositorios de GitHub con Brevo para hacer seguimiento de la interacción de desarrolladores, automatizar flujos de notificación de releases y monitorizar la actividad de la comunidad a través de Tajo. ## Resumen | Propiedad | Valor | | --- | --- | | **Plataforma** | GitHub | | **Categoría** | Personalizada | | **Complejidad de configuración** | Moderada | | **Integración oficial** | No | | **Datos sincronizados** | Eventos, Usuarios, Repositorios | | **Tipo de API** | REST API, GraphQL API | | **Autenticación** | GitHub App / Personal Access Token / OAuth 2.0 | | **URL base** | `https://api.github.com` | | **Versión de la API** | `2022-11-28` (versionado por cabecera) | ## Funcionalidades - **Seguimiento de issues y PR** - Sincroniza eventos de issues y pull requests con las cronologías de contacto de Brevo - **Notificaciones de releases** - Dispara campañas de Brevo al publicar nuevas versiones de los repositorios - **Sincronización de colaboradores** - Asocia colaboradores de GitHub con contactos de Brevo para el engagement de la comunidad - **Seguimiento de stars y forks** - Monitoriza métricas de popularidad del repositorio - **Reenvío de eventos de webhook** - Reenvía los eventos de GitHub a las automatizaciones de Brevo - **Catálogo de repositorios** - Sincroniza los metadatos del repositorio como elementos del catálogo de Brevo ## Requisitos previos Antes de empezar, asegúrate de tener: 1. Una cuenta de GitHub con acceso a los repositorios objetivo 2. Una GitHub App o un Personal Access Token (fine-grained recomendado) 3. Acceso de administrador a los repositorios para configurar los webhooks 4. Una cuenta de Brevo con acceso a la API 5. Una cuenta de Tajo con suscripción activa ## Autenticación GitHub admite varios métodos de autenticación. Tajo recomienda usar GitHub Apps para accesos a nivel de organización. ### Opción 1: GitHub App (recomendada) 1. Ve a **Settings** > **Developer settings** > **GitHub Apps** 2. Haz clic en **New GitHub App** 3. Configura la app con estos permisos: ``` 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 ``` ### Opción 2: Personal Access Token fine-grained 1. Ve a **Settings** > **Developer settings** > **Personal access tokens** > **Fine-grained tokens** 2. Haz clic en **Generate new token** 3. Selecciona los repositorios objetivo 4. Concede estos permisos: ``` Repository access: Selected repositories Permissions: Issues: Read-only Pull requests: Read-only Contents: Read-only Metadata: Read-only ``` Seguridad de los tokens Los tokens fine-grained tienen fecha de expiración. Configura la rotación antes de que expiren. Los tokens de instalación de GitHub App se refrescan automáticamente y son preferibles para producción. ### Conectar con Tajo ```bash # Using GitHub App tajo connectors install github \ --app-id $GITHUB_APP_ID \ --private-key-path ./github-app-key.pem \ --installation-id $GITHUB_INSTALLATION_ID # Using Personal Access Token tajo connectors install github \ --token $GITHUB_TOKEN ``` ## Configuración ### Configuración básica ```yaml connectors: github: enabled: true auth_type: "github_app" # or "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 ``` ### Asignación de campos Asocia los datos de usuario de GitHub con los atributos de contacto de Brevo: ```yaml field_mapping: # Standard fields login: GITHUB_USERNAME email: email name: FIRSTNAME # Developer metrics contributions: GITHUB_CONTRIBUTIONS repositories_count: GITHUB_REPOS followers: GITHUB_FOLLOWERS created_at: GITHUB_JOINED # Custom attributes company: COMPANY location: LOCATION bio: GITHUB_BIO ``` ## Endpoints de la API Tajo se integra con los siguientes endpoints de la REST API de GitHub: | Endpoint | Método | Propósito | | --- | --- | --- | | `/repos/{owner}/{repo}/issues` | GET | Listar issues del repositorio | | `/repos/{owner}/{repo}/pulls` | GET | Listar pull requests | | `/repos/{owner}/{repo}/releases` | GET | Listar releases | | `/repos/{owner}/{repo}/contributors` | GET | Listar colaboradores | | `/repos/{owner}/{repo}/stargazers` | GET | Listar stargazers | | `/repos/{owner}/{repo}/forks` | GET | Listar forks | | `/repos/{owner}/{repo}/events` | GET | Listar eventos del repositorio | | `/users/{username}` | GET | Obtener perfil de usuario | | `/orgs/{org}/members` | GET | Listar miembros de la organización | | `/repos/{owner}/{repo}/hooks` | POST | Crear webhook | ## Ejemplos de código ### Inicializar el conector ```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 }); ``` ### Sincronizar colaboradores con 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 // } ``` ### Gestionar eventos de webhook ```javascript app.post('/webhooks/github', async (req, res) => { const signature = req.get('X-Hub-Signature-256'); const event = req.get('X-GitHub-Event'); // Verify webhook signature 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'); }); ``` ### Disparar una campaña de release ```javascript // Listen for new releases and trigger Brevo campaign 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 } }); }); ``` ## Límites de velocidad GitHub aplica límites de velocidad según el método de autenticación: | Autenticación | Límite de velocidad principal | Search API | | --- | --- | --- | | **Sin autenticar** | 60 peticiones/hora | 10 peticiones/minuto | | **Personal Access Token** | 5.000 peticiones/hora | 30 peticiones/minuto | | **GitHub App (instalación)** | 5.000 peticiones/hora | 30 peticiones/minuto | | **GitHub App (user-to-server)** | 5.000 peticiones/hora | 30 peticiones/minuto | Peticiones condicionales Tajo usa peticiones condicionales (cabeceras `If-None-Match` / `If-Modified-Since`) para reducir el consumo de la API. Las respuestas `304 Not Modified` no cuentan para los límites de velocidad. Límites adicionales: - **Límites de velocidad secundarios**: No más de 100 peticiones concurrentes. No más de 900 puntos por minuto para los endpoints de la REST API. - **GraphQL**: 5.000 puntos por hora (el coste de la consulta varía según la complejidad). ## Resolución de problemas ### Problemas habituales | Problema | Causa | Solución | | --- | --- | --- | | 401 Unauthorized | Token expirado o credenciales incorrectas | Regenera el token o reinstala la GitHub App | | 403 Forbidden | Permisos insuficientes | Revisa los scopes del token o los permisos de la App | | 404 Not Found | Repositorio privado sin acceso | Concede acceso al repositorio al token o App | | Límite de velocidad superado | Demasiadas llamadas a la API | Activa las peticiones condicionales y reduce la frecuencia de sincronización | | Los webhooks no se reciben | URL incorrecta o firewall | Verifica que la URL del webhook sea accesible públicamente | ### Modo depuración ```yaml connectors: github: debug: true log_level: verbose log_webhooks: true ``` ### Probar la conexión ```bash tajo connectors test github # ✓ API authentication successful # ✓ Repository access verified # ✓ Issue data readable # ✓ Webhook delivery active # ✓ Rate limit healthy (4,850/5,000 remaining) ``` ## Buenas prácticas 1. **Usa GitHub Apps en lugar de PATs** - Las GitHub Apps ofrecen permisos granulares y tokens con refresh automático 2. **Activa los secretos de webhook** - Verifica siempre las firmas de webhook con HMAC-SHA256 3. **Usa peticiones condicionales** - Aprovecha los ETags para no malgastar la cuota de límite 4. **Pagina las respuestas grandes** - GitHub devuelve un máx. de 100 elementos por página; itera con las cabeceras `Link` 5. **Sincroniza en momentos de baja actividad** - Programa las sincronizaciones completas fuera de las horas punta de desarrollo 6. **Monitoriza las cabeceras de límite** - Revisa `X-RateLimit-Remaining` para aplicar throttle de forma proactiva ## Seguridad - **Autenticación con GitHub App** - JWT basado en clave RSA con tokens de instalación de corta duración - **Firmas de webhook** - Verificación HMAC-SHA256 en todos los payloads de webhook - **Tokens fine-grained** - Limitados a repositorios y permisos específicos - **Solo HTTPS** - Toda la comunicación con la API se cifra vía TLS 1.2+ - **Almacenamiento cifrado** - Claves privadas y tokens cifrados en reposo en Tajo - **Expiración de tokens** - Los tokens fine-grained expiran automáticamente; configura alertas de rotación ## Recursos relacionados - [Conector de Jira](https://tajo.io/es/docs/connectors/custom/jira) - [Conector de Linear](https://tajo.io/es/docs/connectors/custom/linear) - [Conector de Notion](https://tajo.io/es/docs/connectors/custom/notion) - [API de contactos de Brevo](https://tajo.io/es/docs/contact-management)