git-deploy-webhook

Express middleware for handling GitHub, GitLab, and Bitbucket webhooks with automated deployment commands.

Installation

npm install git-deploy-webhook

Usage

const express = require("express");
const cors = require("cors");
const helmet = require("helmet");
const createWebhookHandler = require("git-deploy-webhook");

const app = express();

app.use(helmet());
app.use(cors());
app.use(express.json());

app.use(
  "/webhook",
  createWebhookHandler({
    webhookSecret: process.env.WEBHOOK_SECRET,
    targetRepo: process.env.TARGET_REPO,
    commands: ["git pull"],
  }),
);

app.listen(3000, () => console.log("Server running"));

Options

| Option | Type | Required | Default | Description | | ------------------- | --------- | -------- | ------------- | ------------------------------------------------ | | webhookSecret | string | Yes | - | Webhook secret (token) | | targetRepo | string | Yes | - | Target repository in format owner/repo | | commands | string[] | No | [] | Commands to execute after webhook trigger | | provider | string | No | "github" | Provider: github, gitlab, or bitbucket | | targetBranch | string | No | - | Only process webhooks for this branch | | verifyProviderIP | boolean | No | false | Verify request IP is from the provider | | customIPs | string[] | No | Provider IPs | Custom IP ranges to allow | | persistCommits | boolean | No | false | Enable commit tracking memory management | | commitRetention | number | No | 1000 | Max commits to keep in memory |

Endpoints

POST /

Main webhook endpoint. Requires provider-specific signature header.

GET /ping

Health check endpoint for webhook verification.

curl https://your-server.com/webhook/ping
# Response: { "status": "ok", "timestamp": "2026-02-22T..." }

Provider Setup

GitHub

1. Go to your repository on GitHub
2. Settings → Webhooks → Add webhook
3. Set Payload URL to your server URL (e.g., https://your-server.com/webhook)
4. Set Content type to application/json
5. Add your webhook secret
6. Select "Let me select individual events" → check "Pushes"

createWebhookHandler({
  webhookSecret: "github_secret",
  targetRepo: "owner/repo",
  provider: "github",
  commands: ["git pull"],
});

GitLab

1. Go to your project on GitLab
2. Settings → Webhooks
3. Set URL to your server (e.g., https://your-server.com/webhook)
4. Set Secret token to your webhook secret
5. Check "Push" events
6. Add webhook

createWebhookHandler({
  webhookSecret: "gitlab_token",
  targetRepo: "group/project",
  provider: "gitlab",
  commands: ["git pull"],
});

Bitbucket

1. Go to your repository on Bitbucket
2. Repository settings → Webhooks → Add webhook
3. Set URL to your server (e.g., https://your-server.com/webhook)
4. Set Secret to your webhook secret
5. Check "Push" as trigger

createWebhookHandler({
  webhookSecret: "bitbucket_secret",
  targetRepo: "workspace/repo",
  provider: "bitbucket",
  commands: ["git pull"],
});

Examples

Basic deployment

createWebhookHandler({
  webhookSecret: "secret",
  targetRepo: "owner/repo",
  commands: ["git pull"],
});

Branch-specific deployment

createWebhookHandler({
  webhookSecret: "secret",
  targetRepo: "owner/repo",
  targetBranch: "main",
  commands: ["git pull origin main"],
});

With IP verification

createWebhookHandler({
  webhookSecret: "secret",
  targetRepo: "owner/repo",
  commands: ["npm run deploy"],
  verifyProviderIP: true,
});

GitLab with IP verification

createWebhookHandler({
  webhookSecret: "gitlab_token",
  targetRepo: "group/project",
  provider: "gitlab",
  commands: ["git pull"],
  verifyProviderIP: true,
});

Full options

createWebhookHandler({
  webhookSecret: process.env.WEBHOOK_SECRET,
  targetRepo: "owner/repo",
  targetBranch: "production",
  provider: "github",
  commands: [
    "git fetch origin production",
    "git checkout production",
    "git pull",
    "npm install",
    "npm run build",
  ],
  verifyProviderIP: true,
  persistCommits: true,
  commitRetention: 500,
});

Response

Success response:

{
  "message": "Webhook received",
  "repo": "owner/repo",
  "commits": 1
}

Error responses:

{ "error": "Missing signature or secret" }
{ "error": "Invalid signature" }
{ "error": "Invalid token" }
{ "error": "IP not allowed" }
{ "error": "Commands failed", "details": "..." }

Deduplication

The package tracks processed commits by ID to prevent duplicate executions. Use persistCommits: true with commitRetention to manage memory on long-running servers.

Access processed commits programmatically:

const handler = createWebhookHandler({ ... });
handler.getProcessedCommits(); // Array of commit IDs
handler.clearProcessedCommits(); // Reset tracking