Conector de GitHub

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

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

Conectar con Tajo

# 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

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:

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:

Ejemplos de código

Inicializar el conector

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

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

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

// 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:

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

Modo depuración

connectors:
  github:
    debug: true
    log_level: verbose
    log_webhooks: true

Probar la conexión

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
• Conector de Linear
• Conector de Notion
• API de contactos de Brevo