Webhook Deployment

A lean Flask-based webhook that executes deployments via a configurable pipeline. Each service has its own configuration. For most use cases, a POST to /deploy is sufficient. If multiple branch variants are stored in the configuration, you can optionally use /deploy/<selector> (e.g., /deploy/dev).

Description

Depending on the configuration, the webhook executes a sequence of steps.

The app is generic. You operate a separate instance for each service, each with its own configuration file.

Features

• Token-based authentication
• Uniform, structured JSON responses (including command outputs)
• Separate configuration per instance
• Optional multiple target variants per selector (e.g., dev/prod)
• Systemd-compatible

Installation

Prerequisites

• Python 3.x
• Flask (pip install flask)
• Git

Step-by-step

1. Create project directory:

   mkdir -p ~/webhook
   cd ~/webhook
   

2. Create and activate virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install flask
   

4. Place app file:

   • Place the generic app.py in this directory.
   • The app loads a config.py from the same directory or an alternative module via the CONFIG_MODULE environment variable.

5. Choose configuration:

   • Example configurations are located under examples/.
   • For each instance, take a suitable file and adapt it.

   Option A: Copy example and use as config.py

   cp examples/mdbook.py config.py
   # Then adjust values in config.py (Token, paths, branches, ...)
   

   Option B: Use example directly (without copying) via environment variable

   export CONFIG_MODULE=examples.mdbook
   

6. Start:

   venv/bin/python app.py
   

   The default port is 5000. If necessary, adjust the port in app.py.

Systemd setup

Example service file:

[Unit]
Description=Generic Deploy Webhook
After=network.target

[Service]
User=youruser
WorkingDirectory=/home/youruser/webhook
Environment=CONFIG_MODULE=examples.mdbook
ExecStart=/home/youruser/webhook/venv/bin/python app.py
Restart=on-failure

[Install]
WantedBy=multi-user.target

Activate:

sudo systemctl daemon-reload
sudo systemctl enable --now deploy-webhook.service
sudo systemctl status deploy-webhook.service

Usage

• Standard: A POST to /deploy is sufficient.
• If variants are stored in the configuration (e.g., dev/prod), you can additionally call /deploy/<selector>.
• Authentication via header: Authorization: Bearer <TOKEN>

Examples:

# Simple call (one branch/variant)
curl -X POST \
  -H "Authorization: Bearer SECRET" \
  http://localhost:5000/deploy

# With selector (if BRANCH_OVERRIDES/DEFAULT_SELECTOR are used)
curl -X POST \
  -H "Authorization: Bearer SECRET" \
  http://localhost:5000/deploy/dev

Responses

Success (200):

{
  "status": "ok",
  "message": "Git updated (dev). mdBook built → /var/www/dev.example.com.",
  "steps": [
    {
      "command": "git -C /srv/docs switch develop",
      "status": "success",
      "stdout": "Switched to branch 'develop'"
    },
    {
      "command": "git -C /srv/docs pull --ff-only",
      "status": "success",
      "stdout": "Already up to date."
    },
    {
      "command": "/home/user/.cargo/bin/mdbook build /srv/docs -d /var/www/dev.example.com",
      "status": "success"
    }
  ]
}

Error (500):

{
  "status": "error",
  "message": "Deploy failed.",
  "step": {
    "command": "git -C /srv/docs pull --ff-only",
    "status": "error",
    "returncode": 1,
    "stdout": "",
    "stderr": "error: ..."
  }
}

License

See LICENSE.