📚 Documentation

NexusCMS Deploy is a self-hosted service that listens to push and tag webhooks from GitHub, GitLab, and Bitbucket, then delivers rich Discord embeds to the right channel automatically — with smart routing, encrypted secrets, and delivery analytics.

This documentation covers everything from first deployment to advanced API usage.

Architecture overview

The application is a Node.js 22 + Express server with a SQLite (default) or PostgreSQL backend. All state is stored in the database — there is no external cache or broker required. An in-memory notification queue with exponential backoff handles Discord delivery retries.

  Git provider  ─── POST /webhooks/{github|gitlab|bitbucket} ──▶  Signature validation
                                                                         │
                                                              Parse & store deploy event
                                                                         │
                                                             Match Discord routing rules
                                                                         │
                                                           Notification queue (retries)
                                                                         │
                                                              Discord Webhook URL ──▶ 💬

🚀 Quick Start

Get NexusCMS Deploy running in under five minutes using Docker Compose.

1. 1

   Clone the repository

   bash

   git clone https://github.com/your-org/nexuscms-deploy.git
   cd nexuscms-deploy

2. 2

   Create your environment file

   Copy the example and fill in your values:

   bash

   cp .env.example .env

   Minimum required variables:

   env

   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
   JWT_SECRET=your-super-secret-jwt-key-min-32-chars
   ENCRYPTION_KEY=64-char-hex-key   # see Configuration section

3. 3

   Start the stack

   bash

   docker compose up -d

   The dashboard will be available at http://localhost:3000.

4. 4

   Register your first user

   bash

   curl -s -X POST http://localhost:3000/api/auth/register \
     -H "Content-Type: application/json" \
     -d '{"email":"[email protected]","password":"changeme","name":"Admin"}' | jq

   Save the returned token — you'll use it as a Bearer token for all API calls.

5. 5

   Register a webhook in your Git provider

   Point the webhook URL to your server and select push events:

   text

   https://your-server.com/webhooks/github
   https://your-server.com/webhooks/gitlab
   https://your-server.com/webhooks/bitbucket

⚙️ Configuration

All configuration is done via environment variables. Copy .env.example to .env and adjust as needed.

Environment variables reference

Generating secrets

# JWT_SECRET (48-byte hex)
node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

# ENCRYPTION_KEY (32-byte hex)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Webhook secret (random 32-byte string)
openssl rand -hex 32

🐳 Docker Deployment

The included docker-compose.yml sets up the application with a PostgreSQL 16 database and a persistent volume.

Starting the stack

# Start all services in the background
docker compose up -d

# View live logs
docker compose logs -f app

# Stop the stack
docker compose down

Health check

The container exposes a health endpoint that Docker uses internally and you can poll externally:

curl http://localhost:3000/health
# → {"status":"ok","timestamp":"2026-04-25T18:00:00.000Z"}

Upgrading

git pull
docker compose build --no-cache
docker compose up -d

🔗 Webhook Setup

GitHub

1. Go to your repository → Settings → Webhooks → Add webhook.
2. Set Payload URL to https://your-server.com/webhooks/github.
3. Set Content type to application/json.
4. Set Secret to the value you used for GITHUB_WEBHOOK_SECRET.
5. Select Just the push event (or individual events — only push is processed).
6. Enable the webhook and click Add webhook.

GitLab

1. Go to your project → Settings → Webhooks.
2. Set URL to https://your-server.com/webhooks/gitlab.
3. Set Secret token to the value you used for GITLAB_WEBHOOK_TOKEN.
4. Check Push events and Tag push events.
5. Click Add webhook.

Bitbucket Cloud

1. Go to your repository → Repository settings → Webhooks → Add webhook.
2. Set URL to https://your-server.com/webhooks/bitbucket.
3. Set Secret to the value you used for BITBUCKET_WEBHOOK_SECRET.
4. Under Triggers, select Repository push.
5. Click Save.

Per-repository Signing Secrets

The global environment variables (GITHUB_WEBHOOK_SECRET etc.) apply to all repositories. For per-repository secrets, use the Secrets tab in the dashboard or the Webhook Secrets API. Per-repository secrets take precedence over the global one when present.

🔐 API Reference — Authentication

All protected endpoints require a Bearer JWT token in the Authorization header. Obtain a token by registering or logging in.

{
  "user": { "id": 1, "email": "[email protected]", "name": "Admin", "plan": "starter" },
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

{ "user": { ... }, "token": "eyJhbGciOiJIUzI1NiIs..." }

{
  "user": { "id": 1, "email": "[email protected]", "name": "Admin", "plan": "pro" },
  "plan": { "routes": { "used": 3, "limit": null }, "secrets": { "used": 5, "limit": null } }
}

{ "api_key": "nx_live_a1b2c3d4..." }

📋 API Reference — Deploys

All deploy endpoints require authentication.

{
  "data": [
    {
      "id": 42,
      "repository": "org/frontend",
      "branch": "main",
      "provider": "github",
      "commit_count": 3,
      "discord_sent": true,
      "created_at": "2026-04-25T17:00:00.000Z"
    }
  ],
  "total": 284,
  "page": 1,
  "limit": 20
}

{ "ok": true, "deployId": 42, "messageId": "1234567890123456789" }

🔀 API Reference — Discord Routes

Routing rules define which Discord channel receives notifications based on repository, branch and event type.

{ "ok": true }

{
  "matched": { "id": 3, "name": "Production", "webhook_url": "https://discord..." },
  "fallbackToDefault": false
}

🔑 API Reference — Webhook Secrets

Per-repository signing secrets take precedence over the global environment variable when validating incoming webhook payloads. Secrets are stored encrypted with AES-256-GCM.

📊 API Reference — Stats & Queue

{ "status": "ok", "timestamp": "2026-04-25T18:00:00.000Z" }

🗺️ Guide — Smart Routing

Route different deploy events to different Discord channels using glob-based matching rules.

How rules are evaluated

1. All enabled rules are sorted by priority (ascending — lower number wins).
2. Each rule is tested against the incoming deploy's repository, branch, and event_type.
3. The first matching rule wins and its webhook_url is used.
4. If no rule matches, the global DISCORD_WEBHOOK_URL is used as fallback.

Glob pattern examples

Example setup

// Rule 1 — priority 1: tag releases → #releases
{
  "name": "Tag Releases",
  "webhook_url": "https://discord.com/api/webhooks/.../releases",
  "match_event_type": "tag",
  "priority": 1
}

// Rule 2 — priority 5: production branch → #prod-deploys
{
  "name": "Production",
  "webhook_url": "https://discord.com/api/webhooks/.../prod",
  "match_branch": "main",
  "match_event_type": "push",
  "priority": 5
}

// Rule 3 — priority 10: everything else → #staging-deploys
{
  "name": "Staging catch-all",
  "webhook_url": "https://discord.com/api/webhooks/.../staging",
  "priority": 10
}

📝 Guide — Release Changelogs

When a tag push is received, NexusCMS Deploy automatically generates a structured changelog grouped by conventional commit type.

How it works

1. A tag push event is received (e.g. v2.3.0).
2. Commits are parsed for conventional commit prefixes: feat, fix, chore, docs, refactor, perf, test, etc.
3. Breaking changes (! suffix or BREAKING CHANGE footer) are detected and surfaced.
4. The version is automatically classified as major, minor, or patch.
5. The changelog is stored on the deploy and available via the changelog API endpoints.

Downloading a changelog

# Download as Markdown
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/deploys/42/changelog.md -o changelog.md

# Download as JSON
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/deploys/42/changelog.json -o changelog.json

🔐 Guide — Secret Encryption

Webhook signing secrets are stored at rest using AES-256-GCM authenticated encryption when ENCRYPTION_KEY is configured.

Generating the key

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# e.g. → 4a7f3c2e1b9d8a6f5e4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e

Add this value to your .env file:

ENCRYPTION_KEY=4a7f3c2e1b9d8a6f5e4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e

Key rotation

There is no automatic key rotation at this time. To rotate: delete all secrets from the dashboard, update ENCRYPTION_KEY, restart the application, and re-enter all secrets.