# Github Integration

> Guide for setting up and managing Docklift's GitHub App integration. Use when this capability is needed.

- Skill: `tomevault-io/github-integration-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/github-integration-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/github-integration-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/github-integration-3

---


# GitHub Integration Guide

Docklift integrates with GitHub using a GitHub App. This allows for accessing private repositories and receiving webhook events (push) for auto-deployments.

## Architecture

-   **Routes**: `backend/src/routes/github.ts`
-   **Service**: `backend/src/services/git.ts` (for cloning/pulling)
-   **Authentication**: Uses JWT signed with a private key to authenticate as the GitHub App.

## Setup Flow (Manifest Flow)

1.  **Initiation**: User clicks "Connect GitHub" in UI.
2.  **Manifest Generation**: `POST /api/github/manifest` generates a GitHub App manifest.
3.  **Redirect**: User is redirected to GitHub to create the app.
4.  **Callback**: GitHub redirects back to `/api/github/manifest/callback` with a code.
5.  **Exchange**: Backend exchanges code for App Credentials (ID, Client ID, Secret, Private Key, Webhook Secret).
6.  **Storage**: Credentials are stored in the `Settings` table in the database.
7.  **Installation**: User is redirected to install the newly created app on their account/orgs.

## Key Components

### Repository Listing
-   **Endpoint**: `GET /api/github/repos`
-   **Logic**: Fetches repositories from **all** installations accessible to the App.
-   **Important**: Uses pagination to ensure all repositories are retrieved (recursively fetching all pages).

### Webhooks (Auto-Deploy)
-   **Endpoint**: `POST /api/github/webhook`
-   **Event**: Listen for `push` events.
-   **Logic**: 
    1.  Verifies HMAC signature **FIRST** — before any database queries (prevents unauthenticated DB lookups). Uses `req.rawBody` captured via `express.json({ verify })` callback for accurate comparison.
    2.  Matches repository URL from payload with `Project` database entries.
    3.  Triggers deployment for matching projects with `auto_deploy: true`.
    4.  Debounced via `recentDeploys` Map with 10-second cooldown per project.

### Authentication
-   **App Auth**: Uses `jsonwebtoken` to sign a JWT with the stored Private Key (`RS256`).
-   **Installation Auth**: Uses the App JWT to request an "Installation Token" for specific API acts (like cloning or fetching repos).

## Troubleshooting

-   **"Repositories not loading"**: Check if the App is installed on the specific GitHub account.
-   **"Webhook not triggering"**: Verify the `webhook_secret` in DB matches GitHub. Check if `auto_deploy` is enabled for the project.
-   **"Authentication Failed"**: The Private Key might be missing or invalid in the database.

## Useful Database Settings (`Settings` table)
-   `github_app_id`
-   `github_private_key`
-   `github_webhook_secret`
-   `github_installation_id` (Default installation ID)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/ssujitx) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->