https://github.com/nkorai/codepipeline-mqtt-notifier-cdk-construct
npm install codepipeline-mqtt-notifier-cdk-constructhttps://github.com/nkorai/codepipeline-mqtt-notifier-cdk-construct
> AWS CDK Construct to forward CodePipeline events to an MQTT broker (with optional Tailscale integration).
> Ideal for home automation, dashboards, build monitors, and custom pipeline notifications.
---
- Instantly forward AWS CodePipeline state change events to your MQTT broker.
- Supports home/remote brokers via Tailscale (optional, private networking).
- Managed Secrets: Securely store MQTT and Tailscale credentials in AWS Secrets Manager (created automatically if enabled).
- Configurable VPC, subnet, and security group support for Lambda.
- Plug-and-play: Auto-creates secrets with placeholder values for first-time setup.
- Customizable Lambda handler (Node.js, MQTT.js, with Tailscale support built-in).
---
``bash`
npm install codepipeline-mqtt-notifier-cdk-construct
`ts
import { CodePipelineMqttNotifier } from "codepipeline-mqtt-notifier-cdk-construct";
new CodePipelineMqttNotifier(this, "Notifier", {
pipelineArnOrName: "arn:aws:codepipeline:us-east-1:123456789012:MyPipeline",
mqttTopic: "pipelines/my-pipeline",
mqttBrokerHost: "100.x.y.z", // Tailscale IP or public/static IP of your broker
});
`
This will:
- Deploy a Lambda function triggered by CodePipeline state change events.
- Send each event as JSON to your MQTT broker on the topic you specify.
---
`ts
import { Vpc, SecurityGroup, SubnetType } from "aws-cdk-lib/aws-ec2";
const vpc = Vpc.fromLookup(this, "Vpc", { vpcId: "vpc-xxxxxx" });
const sg = new SecurityGroup(this, "LambdaSG", { vpc, allowAllOutbound: true });
new CodePipelineMqttNotifier(this, "Notifier", {
pipelineArnOrName: "arn:aws:codepipeline:us-east-1:123456789012:MyPipeline",
mqttTopic: "pipelines/my-pipeline",
mqttBrokerHost: "100.x.y.z",
enableTailscale: true,
enableMqttAuth: true,
});
`
- If enableTailscale is true, a secret for the Tailscale Auth Key is created.enableMqttAuth
- If is true, secrets for MQTT broker username and password are created.
- Update secrets in AWS Secrets Manager after deployment with real values.
---
Secrets are auto-created as needed, with clear placeholder values.
- Tailscale Auth Key:
Used for private Tailscale integration (see Tailscale Keys: https://login.tailscale.com/admin/settings/keys).
- MQTT Username/Password:
Only needed if your broker requires them.
After deploying, update the secret values in AWS Secrets Manager with your real credentials.
---
Each event is sent as a JSON payload on the topic you choose, with this shape:
`json`
{
"eventSource": "aws.codepipeline",
"detailType": "CodePipeline Pipeline Execution State Change",
"pipeline": "MyPipeline",
"state": "SUCCEEDED",
"time": "2025-07-30T20:00:00Z",
"raw": {
/ Full AWS EventBridge event /
}
}
---
`json`
{
"eventSource": "aws.codepipeline",
"detailType": "CodePipeline Pipeline Execution State Change",
"pipeline": "MyPipeline",
"state": "STARTED",
"time": "2025-07-30T20:00:00Z",
"raw": {
/ ... /
}
}
`json`
{
"eventSource": "aws.codepipeline",
"detailType": "CodePipeline Pipeline Execution State Change",
"pipeline": "MyPipeline",
"state": "IN_PROGRESS",
"time": "2025-07-30T20:01:30Z",
"raw": {
/ ... /
}
}
`json`
{
"eventSource": "aws.codepipeline",
"detailType": "CodePipeline Pipeline Execution State Change",
"pipeline": "MyPipeline",
"state": "SUCCEEDED",
"time": "2025-07-30T20:02:50Z",
"raw": {
/ ... /
}
}
`json`
{
"eventSource": "aws.codepipeline",
"detailType": "CodePipeline Pipeline Execution State Change",
"pipeline": "MyPipeline",
"state": "FAILED",
"time": "2025-07-30T20:02:50Z",
"raw": {
/ ... /
}
}
States you may see include: STARTED, RESUMED, CANCELED, FAILED, SUCCEEDED, SUPERSEDED, IN_PROGRESS.
---
- If you see placeholder warnings in CloudWatch logs, update the corresponding secret value in AWS Secrets Manager.
- Tailscale startup adds a few seconds per cold start.
- If Lambda cannot connect to your MQTT broker, check VPC, subnet, and security group settings.
- No credentials are required on MQTT clients—everything is push-based from AWS.
- Lambda code loads secrets at runtime using the AWS SDK for best security.
---
- Secrets are never hard-coded in Lambda, only read securely at runtime.
- The minimum privileges needed are automatically granted to the Lambda.
- Construct creates secrets with names like , etc.
---
- Pull requests welcome!
- See lambda/mqtt-notifier/index.js for Lambda source.
- Please open an issue or PR if you add support for other event types or protocols.
---
To test your Lambda locally with full Tailscale support, use:
`bash`
docker build -t mqtt-lambda-tailscale .
Install the SAM CLI, then:
`bash`
sam build
sam local invoke MqttNotifierFunction --env-vars env.json -e event.json --docker-network host --use-container
- Make sure env.json includes the required environment variables (MQTT broker, topic, secrets ARNs, etc.)event.json
- should be shaped like an EventBridge CodePipeline state change event, an example is provided and other examples are provided in the README above.--docker-network host` ensures your container can reach LAN-local MQTT brokers.
-
---
MIT
---
Open an issue or PR at: https://github.com/nkorai/codepipeline-mqtt-notifier-cdk-construct/issues