GitHub Connector

Connect your GitHub repositories to Brevo for developer engagement tracking, release notification workflows, and community activity monitoring through Tajo.

Overview

Features

• Issue and PR tracking - Sync issue and pull request events to Brevo contact timelines
• Release notifications - Trigger Brevo campaigns on new repository releases
• Contributor sync - Map GitHub contributors to Brevo contacts for community engagement
• Star and fork tracking - Monitor repository popularity metrics
• Webhook event forwarding - Forward GitHub events to Brevo automations
• Repository catalog - Sync repository metadata as Brevo catalog items

Prerequisites

Before you begin, ensure you have:

1. A GitHub account with access to target repositories
2. A GitHub App or Personal Access Token (fine-grained recommended)
3. Admin access to repositories for webhook configuration
4. A Brevo account with API access
5. A Tajo account with an active subscription

Authentication

GitHub supports multiple authentication methods. Tajo recommends using GitHub Apps for organization-level access.

Option 1: GitHub App (Recommended)

1. Navigate to Settings > Developer settings > GitHub Apps
2. Click New GitHub App
3. Configure the app with these permissions:

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

Option 2: Fine-Grained Personal Access Token

1. Go to Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Click Generate new token
3. Select target repositories
4. Grant these permissions:

Repository access: Selected repositories
Permissions:
  Issues: Read-only
  Pull requests: Read-only
  Contents: Read-only
  Metadata: Read-only

Connecting to 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

Configuration

Basic Setup

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

Field Mapping

Map GitHub user data to Brevo contact attributes:

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

API Endpoints

Tajo integrates with the following GitHub REST API endpoints:

Code Examples

Initialize Connector

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
});

Sync Contributors to 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
// }

Handle Webhook Events

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');
});

Trigger Release Campaign

// 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
    }
  });
});

Rate Limits

GitHub enforces rate limits based on authentication method:

Additional limits:

• Secondary rate limits: No more than 100 concurrent requests. No more than 900 points per minute for REST API endpoints.
• GraphQL: 5,000 points per hour (query cost varies by complexity).

Troubleshooting

Common Issues

Debug Mode

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

Test Connection

tajo connectors test github
# ✓ API authentication successful
# ✓ Repository access verified
# ✓ Issue data readable
# ✓ Webhook delivery active
# ✓ Rate limit healthy (4,850/5,000 remaining)

Best Practices

1. Use GitHub Apps over PATs - GitHub Apps provide granular permissions and auto-refreshing tokens
2. Enable webhook secrets - Always verify webhook signatures with HMAC-SHA256
3. Use conditional requests - Leverage ETags to avoid wasting rate limit quota
4. Paginate large responses - GitHub returns max 100 items per page; iterate with Link headers
5. Sync during low activity - Schedule full syncs outside peak development hours
6. Monitor rate limit headers - Check X-RateLimit-Remaining to proactively throttle

Security

• GitHub App Authentication - RSA key-based JWT with short-lived installation tokens
• Webhook Signatures - HMAC-SHA256 signature verification on all webhook payloads
• Fine-Grained Tokens - Scoped to specific repositories and permissions
• HTTPS Only - All API communication encrypted via TLS 1.2+
• Encrypted Storage - Private keys and tokens encrypted at rest in Tajo
• Token Expiration - Fine-grained tokens auto-expire; set up rotation alerts

Related Resources

• Jira Connector
• Linear Connector
• Notion Connector
• Brevo Contacts API

Open-Source Implementation Map

This section is derived from official or public repository material discovered for the GitHub connector. Use it as the engineering companion to the setup guide above: it shows where the API surface lives, what implementation assets exist, and how Tajo should translate them into reliable Brevo sync behavior.

Repository Snapshot

Integration Shape

graph LR
  Source["GitHub API / repository"] --> Auth["Auth and scopes"]
  Source --> Objects["Objects, events, and schemas"]
  Auth --> Tajo["Tajo connector runtime"]
  Objects --> Tajo
  Tajo --> Brevo["Brevo contacts, attributes, lists, campaigns"]
  Tajo --> Ops["Backfill, cursor, retries, logs"]

What To Reuse

• GitHub’s REST API OpenAPI Description
• This repository contains OpenAPI descriptions for GitHub’s REST API.
• What is OpenAPI?
• From the OpenAPI Specification:
• Project Status

Tajo Revamp Checklist

• Keep authentication setup aligned with the vendor docs and the public repository’s current API shape.
• Map primary resources into explicit Tajo sync objects with stable external IDs.
• Prefer cursor-based or updated-at incremental sync where the API exposes it; otherwise document the fallback.
• Treat webhook handlers as idempotent and replay-safe, especially for order, contact, ticket, and campaign events.
• Capture pagination, rate limits, retry headers, and partial-failure behavior in connector smoke tests.
• Keep examples small and runnable against sandbox or test-mode accounts.

Sources

• github/rest-api-description
• Vendor documentation