Knowledge Base

Overview

This guide walks you through integrating your application with GitHub using OAuth authentication and webhook events. After completing the steps, you’ll be able to:

  • Authenticate users via their GitHub accounts.
  • Listen to repository events (push, pull request, issues).
  • Perform actions on behalf of the user (create issues, comment, etc.).

Prerequisites

  • A GitHub account with admin access to the target repositories.
  • Node.js ≥ 14 (or any runtime you prefer).
  • SSL/TLS certificate for your callback URL (GitHub requires HTTPS).
  • Basic knowledge of REST APIs.

Setup Steps

  1. Create a new OAuth App in GitHub:
    • Navigate to Settings → Developer settings → OAuth Apps.
    • Click New OAuth App and fill in:
      • Application name
      • Homepage URL
      • Authorization callback URL (e.g., https://yourdomain.com/auth/callback)
    • Save to get Client ID and Client Secret.
  2. Store the credentials securely (environment variables recommended).
  3. Install the required package: 
    npm install @octokit/rest dotenv
  4. Configure your server to handle the OAuth flow (see Example Code).
  5. Set up webhooks for the repositories you need to monitor (see Webhooks).

Webhooks

Webhooks deliver real‑time notifications of events. To add a webhook:

  1. Go to the repository → Settings → Webhooks → Add webhook.
  2. Enter the Payload URL (e.g., https://yourdomain.com/webhook).
  3. Select Content type as application/json.
  4. Choose events you want to receive (Push, Pull request, Issues, etc.).
  5. Set a secret token and store it on your server for verification.
  6. Save the webhook.

Sample verification code:

const crypto = require('crypto');
function verifySignature(req, secret) {
  const signature = req.headers['x-hub-signature-256'];
  const hash = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');
  return `sha256=${hash}` === signature;
}

OAuth Authentication Flow

Use the @octokit/oauth-app library to simplify the process.

npm install @octokit/oauth-app

Sample server routes (Express):

const express = require('express');
const { createOAuthAppAuth } = require('@octokit/oauth-app');
require('dotenv').config();

const app = express();
app.set('view engine', 'ejs');

const oauth = createOAuthAppAuth({
  clientId: process.env.GITHUB_CLIENT_ID,
  clientSecret: process.env.GITHUB_CLIENT_SECRET,
});

app.get('/auth/login', (req, res) => {
  const authUrl = `https://github.com/login/oauth/authorize?client_id=${process.env.GITHUB_CLIENT_ID}&redirect_uri=${encodeURIComponent('https://yourdomain.com/auth/callback')}&scope=repo`;
  res.redirect(authUrl);
});

app.get('/auth/callback', async (req, res) => {
  const { code } = req.query;
  const token = await oauth({ type: 'token', code });
  // Store token securely, e.g., in a session or DB.
  res.send('Authentication successful!');
});

app.listen(3000, () => console.log('Server running on :3000'));

Full Example Project

Clone the starter repository for a working example:

git clone https://github.com/yourorg/github-integration-demo.git

The project includes:

  • OAuth login flow
  • Webhook receiver with signature verification
  • Utility functions for creating issues and comments

Troubleshooting

  • Invalid client secret – Ensure the secret is not URL‑encoded and matches the value in GitHub.
  • Webhook signature mismatch – Verify you’re using the exact secret configured in GitHub and that the request body isn’t modified.
  • Redirect URI mismatch – The callback URL must exactly match the one registered in the OAuth App.
  • Rate limiting – Use conditional requests with ETag headers or increase your API quota.