Auto-Deploy with Webhooks

Push to GitHub, automatically deploy. No manual intervention needed.

How It Works

You push to GitHub

Commit and push your changes to your repository

GitHub sends a webhook

GitHub POSTs a signed payload to your server on port 9000

Shyp verifies and deploys

Shyp validates the signature, matches the repo to an app, and triggers deployment

Step 1: Generate a Webhook Secret

The secret ensures only GitHub can trigger deployments. Generate a random string on your server:

# Generate a secure random secret
openssl rand -hex 32

# Example output:
# a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678

Important: Save this secret somewhere safe. You'll need it for both your server and GitHub.

Step 2: Add Secret to Server Environment

Add the secret to your server's environment so Shyp can verify incoming webhooks.

Option A: Add to ~/.bashrc (user-level)

echo 'export SHYP_WEBHOOK_SECRET=your-secret-here' >> ~/.bashrc
source ~/.bashrc

Option B: Add to /etc/environment (system-wide)

sudo bash -c 'echo "SHYP_WEBHOOK_SECRET=your-secret-here" >> /etc/environment'

Requires logout/login or reboot to take effect.

Step 3: Configure GitHub Webhook

Add a webhook to each repository you want to auto-deploy.

Go to your repository on GitHub
Click Settings → Webhooks
Click Add webhook

Payload URL

http://YOUR_SERVER_IP:9000/

Replace YOUR_SERVER_IP with your actual server IP

Content typeapplication/json

Secret

your-webhook-secret

Paste the same secret from Step 1

Events

Just the push event

Select "Just the push event" radio option

ActiveYes (checked)

Step 4: Start the Webhook Server

Start the Shyp webhook listener on your server:

shyp start

This starts a PM2 process named shyp-webhook that listens on port 9000.

# Check if it's running
pm2 status

# View webhook logs
pm2 logs shyp-webhook

Testing Your Webhook

Check from GitHub

After adding the webhook, GitHub shows delivery history:

Go to your repo → Settings → Webhooks
Click on your webhook
Scroll down to "Recent Deliveries"
A green checkmark means successful delivery

Test Manually

You can test the webhook endpoint manually:

# Check if port 9000 is accessible
curl http://YOUR_SERVER_IP:9000/health

# Should return: {"status":"ok"}

Branch Filtering

Shyp only deploys when pushes match the configured branch for each app.

apps/my-app.yaml

name: my-app
repo: git@github.com:you/my-app.git
branch: main   # Only deploys when pushing to main

Pushes to other branches (like develop or feature branches) are ignored.

Multiple Repositories

The same webhook server handles all your apps. Shyp matches the incoming webhook to the correct app by comparing the repository URL.

Tip: You can use the same webhook secret for all your repositories, or generate different secrets for each one (more secure but more to manage).

Troubleshooting

Webhook delivery failed

Check that port 9000 is open in your firewall:

sudo ufw allow 9000/tcp

Signature verification failed

Make sure the SHYP_WEBHOOK_SECRET on your server exactly matches the secret in GitHub. Check for trailing spaces or newlines.

Webhook received but no deployment

Check that the repository URL in your app config matches the webhook payload. View logs with pm2 logs shyp-webhook.