GitHub Integration

Streamline plugin publishing and maintenance with automated GitHub workflows.

Overview

The GitHub Integration feature enables plugin authors to seamlessly publish versions, synchronize documentation, and display installation badges directly from their GitHub repositories.

Key capabilities:

• Auto-publish on Release — New GitHub releases automatically create plugin versions with binary detection
• Content Sync — README and CHANGELOG updates automatically sync to Pumpkin Hub
• Install Badge — Embed a dynamic badge in your GitHub README linking to your Pumpkin Hub plugin
• Webhook Verification — All webhooks are cryptographically signed with HMAC-SHA256

Setup

1. Install the Pumpkin Hub GitHub App

The GitHub App is available at https://github.com/apps/pumpkin-hub-app. You can install it on your personal account, organization, or specific repositories.

2. Sign in to Pumpkin Hub with GitHub

Pumpkin Hub uses your GitHub OAuth session to automatically detect every repository where the App is installed — on your personal account and any organization. No Installation ID is required; the platform resolves it for you.

3. Pick a Repository

On any page that needs a repository (New Plugin → From GitHub, or plugin edit → GitHub Integration), click "Load my GitHub repositories". Pumpkin Hub will list every accessible repository instantly.

Publish from GitHub

The fastest way to create a new plugin on Pumpkin Hub is to publish it directly from an existing GitHub repository.

1. Go to Add Plugin and switch to the From GitHub tab.
2. Click "Load my GitHub repositories" — the picker populates automatically. If returning from GitHub OAuth, repositories are auto-loaded without an extra click.
3. Select the target repository — plugin metadata (name, description) is pre-populated from the GitHub repository data.
4. Refine the details (categories, license, icon), and submit.
5. The plugin is created and immediately linked to the selected repository.

Note: If the App is not yet installed on any of your repositories, the picker displays an empty state with a direct link to the GitHub App installation page.

Linking a Repository

To link an existing plugin to a GitHub repository, open the plugin's edit page and scroll to the GitHub Integration section:

1. Click "Load my GitHub repositories" — the list populates from your GitHub App installations.
2. Select the repository from the dropdown.
3. Toggle the desired options (auto-publish, sync README, sync changelog).
4. Click "Connect Repository".

The linking process validates that:

• The GitHub App is installed on the specified repository
• The plugin owner has write access to the repository
• The repository isn't already linked to another plugin

Once linked, the connection is stored in the database with:

• Repository owner and name
• Default branch (detected from the repository)
• Feature toggles (auto-publish, sync-readme, sync-changelog)
• Installation ID (resolved automatically, not exposed to the user)

You can unlink at any time by clicking "Disconnect Repository" on the edit page.

Auto-Publishing on Release

When a new GitHub release is published and auto-publish is enabled:

1. Version Detection — The release tag is normalized (e.g., v1.2.3 → 1.2.3)
2. Binary Detection — Release assets are scanned for platform binaries:
   • .dll, .exe → Windows
   • .so → Linux
   • .dylib → macOS
3. Binary Upload — Matching binaries are downloaded and stored in S3
4. Version Creation — A new plugin version is created with:
   • Version number from tag
   • Changelog from release notes (first 500 chars)
   • Detected binaries for each platform
   • "Published from GitHub" marker
5. Notification — Author receives a notification about the new version

Content Synchronization

When changes are pushed to the default branch and sync is enabled:

README Sync

• Fetches README.md from the repository
• Updates the plugin's description field on Pumpkin Hub
• Preserves other plugin metadata (name, categories, etc.)

CHANGELOG Sync

• Fetches CHANGELOG.md from the repository (if present)
• Updates the latest version's changelog on Pumpkin Hub
• Only affects the most recent non-yanked version

Last Sync Timestamp: The last_webhook_at field tracks the most recent webhook processing, visible on the plugin edit page.

Installation Badge

Linked plugins generate a dynamic "Download on Pumpkin Hub" badge that displays the current version.

Badge URL

https://api.pumpkin-hub.dev/api/v1/plugins/{slug}/badge.svg

Markdown Snippet

The badge comes with a ready-to-copy Markdown snippet:

[![Download on Pumpkin Hub](https://api.pumpkin-hub.dev/api/v1/plugins/{slug}/badge.svg)](https://pumpkin-hub.dev/plugins/{slug})

Paste this into your GitHub README to display the badge with a link to your Pumpkin Hub plugin page.

Badge Features

• Dynamic Version — Shows the latest available version automatically
• Cached — Updates cached every 5 minutes to avoid excessive generation
• Link Ready — Badge is a clickable link to the plugin on Pumpkin Hub
• Responsive — SVG format, scales to any size

API Endpoints

List My GitHub Repositories

GET /api/v1/github/my-repositories
Authorization: JWT cookie (must be signed in with GitHub OAuth)

Response:
{
  "repositories": [
    {
      "installation_id": 12345678,
      "full_name": "my-org/my-plugin",
      "owner": "my-org",
      "name": "my-plugin",
      "default_branch": "main",
      "description": "An awesome plugin"
    }
  ]
}

Returns all repositories accessible via the Pumpkin Hub GitHub App across all installations (personal account + organizations) matching your GitHub OAuth identity. Returns 422 if your account is not linked to GitHub.

Publish Plugin from GitHub

POST /api/v1/plugins/from-github

{
  "name": "My Plugin",
  "slug": "my-plugin",
  "short_description": "A short description",
  "category_ids": ["uuid"],
  "installation_id": 12345678,
  "repository_owner": "my-org",
  "repository_name": "my-plugin",
  "sync_readme": true,
  "sync_changelog": true,
  "auto_publish": true
}

Response:
{
  "slug": "my-plugin"
}

Creates a plugin and links it to the specified repository in one request. The installation_id is resolved automatically by the frontend from GET /github/my-repositories and never needs to be entered manually.

Link a Repository

POST /api/v1/plugins/{slug}/github/link

{
  "installation_id": 12345678,
  "repository_owner": "my-org",
  "repository_name": "my-plugin",
  "sync_readme": true,
  "sync_changelog": true,
  "auto_publish": true
}

Response:
{
  "id": "uuid",
  "plugin_id": "uuid",
  "installation_id": 12345678,
  "repository_owner": "my-org",
  "repository_name": "my-plugin",
  "repository_full_name": "my-org/my-plugin",
  "default_branch": "main",
  "sync_readme": true,
  "sync_changelog": true,
  "auto_publish": true,
  "last_webhook_at": null,
  "created_at": "2026-03-10T12:34:56Z"
}

Get Link Status

GET /api/v1/plugins/{slug}/github

Response: Same structure as above, or 404 if not linked

Unlink a Repository

DELETE /api/v1/plugins/{slug}/github

Response: 204 No Content

Get Badge SVG

GET /api/v1/plugins/{slug}/badge.svg

Response: SVG image (Content-Type: image/svg+xml)

Webhook Endpoint

POST /api/v1/webhooks/github

GitHub sends:
- X-GitHub-Event: "release" or "push"
- X-Hub-Signature-256: HMAC-SHA256 signature verification
- Payload: Installation ID, repository, event type, etc.