Feature Flag Webhook → GitHub Actions Demo

A webhook receiver service that listens for Harness FME feature flag changes and triggers GitHub Actions workflows. Perfect for demonstrating how feature flag changes can automatically trigger CI/CD pipelines, deployments, tests, and other automated workflows.

Overview

This project demonstrates how to integrate feature flag management with GitHub Actions:

1. Harness FME sends a webhook when a flag changes
2. This webhook receiver processes the payload
3. GitHub Actions workflow is triggered automatically
4. Workflow runs your tests, deployments, or any custom automation

Project Structure

gh-post/
├── server.js                           # Express server
├── src/
│   ├── logger.js                       # Logging utility
│   ├── webhook-handler.js              # Webhook processing logic
│   └── github-dispatcher.js            # GitHub API integration
├── .github/workflows/
│   ├── feature-flag-deploy.yml         # Main demo workflow
│   └── test-dispatch.yml               # Simple test workflow
├── examples/
│   ├── webhook-payload.json            # Sample Harness FME payload
│   └── test-webhook.sh                 # Local testing script
├── package.json
├── .env.example
└── README.md

Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env with your values:

GITHUB_TOKEN=ghp_your_token_here
GITHUB_OWNER=your-github-username
GITHUB_REPO=gh-post
PORT=3000
NODE_ENV=development

3. Create GitHub Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a descriptive name (e.g., "Feature Flag Webhook")
4. Select scopes:
   • Check repo (Full control of private repositories)
   • This includes the necessary actions:write permission
5. Click "Generate token"
6. Copy the token and add it to your .env file

4. Initialize Git Repository (if not already done)

git init
git add .
git commit -m "Initial commit: Feature flag webhook receiver"

5. Push to GitHub

Create a new repository on GitHub named gh-post, then:

git remote add origin https://github.com/YOUR_USERNAME/gh-post.git
git branch -M main
git push -u origin main

This step is important because the GitHub Actions workflows need to exist in your repository for the repository_dispatch event to work.

Usage

Local Testing

1. Start the Server

npm run dev

You should see:

[2025-12-11T...] [INFO] Server started on port 3000
[2025-12-11T...] [INFO] Endpoints:
[2025-12-11T...] [INFO]   POST http://localhost:3000/webhook - Receive feature flag webhooks
[2025-12-11T...] [INFO]   GET  http://localhost:3000/health - Health check

2. Test Health Endpoint

curl http://localhost:3000/health

3. Test Webhook Locally

npm run test

Or manually:

curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -d @examples/webhook-payload.json

4. Verify in GitHub Actions

Go to your GitHub repository → Actions tab. You should see a new workflow run for "Feature Flag Deploy".

Exposing Locally with Ngrok

To receive webhooks from Harness FME, you need to expose your local server:

1. Install Ngrok

# macOS
brew install ngrok

# Or download from https://ngrok.com/download

2. Start Ngrok Tunnel

ngrok http 3000

You'll see output like:

Forwarding  https://abc123def456.ngrok.io -> http://localhost:3000

3. Copy the HTTPS URL

Copy the https:// URL (e.g., https://abc123def456.ngrok.io)

4. Configure Harness FME Webhook

1. Go to your Harness FME project
2. Navigate to FNE Settings → Integrations → Webhooks
3. Add a new Audit Log Webhook
   • URL: https://abc123def456.ngrok.io/webhook

5. Test with Real Feature Flag Changes

1. Go to your Harness FME dashboard
2. Make a change to any feature flag (enable/disable, change targeting, etc.)
3. Watch your server logs for the incoming webhook
4. Check GitHub Actions for the triggered workflow

How It Works

Webhook Flow

Harness FME Feature Flag Change
        ↓
   (HTTP POST)
        ↓
Your Webhook Receiver (this app)
        ↓
Validates & Transforms Payload
        ↓
GitHub API (repository_dispatch)
        ↓
GitHub Actions Workflow Triggered
        ↓
Runs Tests/Deployments/Etc.

Payload Transformation

Harness FME sends:

{
  "name": "new-checkout-flow",
  "environmentName": "production",
  "editor": "developer@example.com",
  ...
}

We transform and send to GitHub:

{
  "event_type": "feature-flag-changed",
  "client_payload": {
    "flag_name": "new-checkout-flow",
    "environment": "production",
    "editor": "developer@example.com",
    ...
  }
}

GitHub Actions receives: Access via ${{ github.event.client_payload.flag_name }}, etc.

GitHub Actions Workflows

feature-flag-deploy.yml

Main workflow that demonstrates:

• Extracting feature flag metadata from the webhook
• Logging change information
• Running tests
• Simulating deployment
• Notification steps

Customize this workflow to:

• Run your actual test suite
• Deploy to staging/production based on environment
• Send Slack/email notifications
• Update documentation
• Trigger dependent workflows

test-dispatch.yml

Simple workflow for testing the integration:

• Can be triggered manually via workflow_dispatch
• Can be triggered via repository_dispatch with test-event type
• Displays all event data for debugging

Customization

Triggering Different Workflows Based on Environment

Edit src/github-dispatcher.js to send different event types:

const eventType = payload.environment === 'production'
  ? 'feature-flag-production'
  : 'feature-flag-staging';

await octokit.repos.createDispatchEvent({
  owner,
  repo,
  event_type: eventType,
  client_payload: payload
});

Then create separate workflows for each event type.

Adding Webhook Security

To add HMAC signature verification:

1. Add to .env:

   WEBHOOK_SECRET=your-secret-key
   

2. Update src/webhook-handler.js:

   const crypto = require('crypto');
   
   function verifySignature(payload, signature) {
     const hmac = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET);
     const digest = hmac.update(JSON.stringify(payload)).digest('hex');
     return crypto.timingSafeEqual(
       Buffer.from(signature),
       Buffer.from(digest)
     );
   }

Troubleshooting

"GitHub authentication failed"

• Verify your GITHUB_TOKEN in .env is correct
• Ensure the token has repo scope
• Check the token hasn't expired

"Repository not found"

• Verify GITHUB_OWNER and GITHUB_REPO are correct
• Ensure you've pushed the repository to GitHub
• Check the GitHub Actions workflows exist in .github/workflows/

Workflow not triggering

• Verify the workflows are committed and pushed to GitHub
• Check that the event_type in the dispatcher matches the workflow trigger
• Look at server logs to confirm the dispatch was sent successfully
• Ensure GitHub Actions is enabled for your repository

Ngrok tunnel not working

• Make sure ngrok is running while testing
• The URL changes each time you restart ngrok (use a static domain with paid plan)
• Verify the webhook URL in Harness matches your current ngrok URL

Production Deployment

For production use, deploy this service to:

• Heroku: git push heroku main
• Railway: Connect your GitHub repo
• Render: Connect your GitHub repo
• Google Cloud Run: Deploy as container
• AWS Lambda: Use serverless framework

Remember to:

1. Set environment variables in your hosting platform
2. Use managed secrets (not .env files)
3. Add webhook signature verification
4. Implement rate limiting
5. Add monitoring and logging
6. Use HTTPS (handled by most platforms automatically)

License

Apache 2.0

Contributing

Feel free to submit issues or pull requests!