---
title: "GitHub Connector"
description: "Complete GitHub integration guide for syncing repository events, issues, pull requests, and developer activity with Brevo via Tajo."
url: https://tajo.io/docs/connectors/custom/github/
markdown: https://tajo.io/docs/connectors/custom/github.md
lang: en-US
robots: noindex
---

# GitHub Connector

Connector status: Planned Not built yet. Tajo does not run this connector today.

| Source field | Destination field | Sample value |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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

## Overview

| Property | Value |
| --- | --- |
| **Platform** | GitHub |
| **Category** | Custom |
| **Setup Complexity** | Moderate |
| **Official Integration** | No |
| **Data Synced** | Events, Users, Repositories |
| **API Type** | REST API, GraphQL API |
| **Authentication** | GitHub App / Personal Access Token / OAuth 2.0 |
| **Base URL** | `https://api.github.com` |
| **API Version** | `2022-11-28` (header-based versioning) |

## 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
```

Token Security

Fine-grained tokens have expiration dates. Set up token rotation before expiry. GitHub App installation tokens auto-refresh and are preferred for production use.

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

## Configuration

### Basic Setup

```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
```

### Field Mapping

Map GitHub user data to Brevo contact attributes:

```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
```

## API Endpoints

Tajo integrates with the following GitHub REST API endpoints:

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/repos/{owner}/{repo}/issues` | GET | List repository issues |
| `/repos/{owner}/{repo}/pulls` | GET | List pull requests |
| `/repos/{owner}/{repo}/releases` | GET | List releases |
| `/repos/{owner}/{repo}/contributors` | GET | List contributors |
| `/repos/{owner}/{repo}/stargazers` | GET | List stargazers |
| `/repos/{owner}/{repo}/forks` | GET | List forks |
| `/repos/{owner}/{repo}/events` | GET | List repository events |
| `/users/{username}` | GET | Get user profile |
| `/orgs/{org}/members` | GET | List organization members |
| `/repos/{owner}/{repo}/hooks` | POST | Create webhook |

## Code Examples

### Initialize Connector

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

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

### Handle Webhook Events

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

### Trigger Release Campaign

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

## Rate Limits

GitHub enforces rate limits based on authentication method:

| Authentication | Primary Rate Limit | Search API |
| --- | --- | --- |
| **Unauthenticated** | 60 requests/hour | 10 requests/minute |
| **Personal Access Token** | 5,000 requests/hour | 30 requests/minute |
| **GitHub App (installation)** | 5,000 requests/hour | 30 requests/minute |
| **GitHub App (user-to-server)** | 5,000 requests/hour | 30 requests/minute |

Conditional Requests

Tajo uses conditional requests (`If-None-Match` / `If-Modified-Since` headers) to reduce API consumption. Responses with `304 Not Modified` do not count against rate limits.

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

| Issue | Cause | Solution |
| --- | --- | --- |
| 401 Unauthorized | Expired token or wrong credentials | Regenerate token or reinstall GitHub App |
| 403 Forbidden | Insufficient permissions | Check token scopes or App permissions |
| 404 Not Found | Private repo without access | Grant repository access to token or App |
| Rate limit exceeded | Too many API calls | Enable conditional requests and reduce sync frequency |
| Webhooks not received | Incorrect URL or firewall | Verify webhook URL is publicly accessible |

### Debug Mode

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

### Test Connection

```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)
```

## 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](https://tajo.io/docs/connectors/custom/jira)
- [Linear Connector](https://tajo.io/docs/connectors/custom/linear)
- [Notion Connector](https://tajo.io/docs/connectors/custom/notion)
- [Brevo Contacts API](https://tajo.io/docs/contact-management)

## 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

| Repository | Commit | Languages / formats | Files |
| --- | --- | --- | --- |
| [github/rest-api-description](https://github.com/github/rest-api-description) | 88dc3d8 | JSON (170), YAML (168), Markdown (12), YAML (10), gitignore (1), txt (1) | 362 |

### Integration Shape

```mermaid
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](https://github.com/github/rest-api-description)
- [Vendor documentation](https://docs.github.com/en/rest)