AWS: Setting up Amplify Deployment Notifications via SNS (OUTDATED)

Matthew Cordaro,•AWSAmplifySNS
Back

THIS IS NOW OUTDATED AS THIS USES OUTDATED AMPLIFY v1 AND AWS-CLI v2

DO NOT USE THESE DIRECTIONS! MOVE TO V2 & V3 respectively for custom hooks!

How to Set Up Email Notifications for AWS Amplify Deployments Using Amazon SNS

AWS Amplify simplifies the process of building, deploying, and hosting web applications. But wouldn’t it be great if you could get real-time email notifications for successful or failed deployments? In this guide, I’ll show you how to integrate Amazon Simple Notification Service (SNS) with Amplify to receive email alerts—while keeping sensitive data secure by using environment variables.

Note: This guide assumes you have aws-sdk installed.

Create an SNS Topic

Start by creating an Amazon SNS topic that will send deployment notifications.

  1. Go to the Amazon SNS Console
  2. Click Create topic and choose Standard as the type
  3. Give your topic a Name, like AmplifyDeploymentNotifications
  4. Click Create topic
  5. Note the ARN, you will need it for later.

Subscribe Your Email Address

To receive notifications, you need to subscribe your email address to the SNS topic.

  1. Navigate to your SNS Topic in the console
  2. Click Create subscription
  3. Set the Protocol to Email
  4. Under Endpoint enter your email address
  5. Click Create subscription
  6. Click the provided link, in the confirmation email that was sent, to confirm the subscription

Add / Modify IAM Role for Amplify

To enable Amplify access to push notifications to the SNS topic, you will need to create a service role.

  1. Navigate to IAM Roles and click on Create role
  2. For Step 1, set Tursted entity type to AWS service and for Use case select Amplify
  3. Click Next twice to get to Step 3
  4. Give it a name like AmplifyServiceRole click Create role
  5. Select the role you just created in the list
  6. Under Permission policies select the dropdown menu that says Add permission and select Create inline policy
  7. Set the editor to JSON and paste in the following 
    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sns:Publish",
            "Resource": "<your-arn>"
        }
    ]
}
  8. Replace <your-arn> with the arn from the SNS Topic you created before
  9. Click Next
  10. Navigate to your Amplify app in the AWS Amplify Console
  11. In the menu, go to App settings > IAM Roles
  12. Set the Service role to the role you just created like AmplifyServiceRole
  13. Click Save

Add an SNS Topic ARN Environment Variable to Amplify

To prevent your SNS topic ARN, from appearing in your source code on GitHub, store it as an environment variable in Amplify.

  1. Navigate to your Amplify app in the AWS Amplify Console
  2. In the menu, go to Hosting > Environment variables
  3. Click Manage variables
  4. Click Add new
  5. Set the Variable to SNS_TOPIC_ARN and Value to the ARN of your SNS topic
  6. Click Save the environment variable.

Create a post-build Hook in Amplify

AWS Amplify supports lifecycle hooks that run custom scripts after deployments. Use the post-build hook to publish messages to your SNS topic.

  1. Create and navigate to the amplify/hooks folder in your project.
  2. Create or update the post-build.js file with the following code: 
    const AWS = require('aws-sdk');
const sns = new AWS.SNS();
 
const run = async () => {
const topicArn = process.env.SNS_TOPIC_ARN;
const branchName = process.env.GIT_BRANCH;
const buildStatus = process.env.AWS_AMPLIFY_BUILD_STATUS;
const buildLogs = process.env.AWS_AMPLIFY_BUILD_LOGS;
const notificationBranches = ['main', 'dev'];
 
    const logInfo = {
        timestamp: new Date().toISOString(),
        topicArn,
        branchName,
        buildStatus,
        isNotificationBranch: notificationBranches.includes(branchName)
    };
 
    if (notificationBranches.includes(branchName)) {
        let message;
        if (buildStatus === 'SUCCEED') {
            message = `✅ Successful deployment to ${branchName}!\n` +
                `🚀 The build and deployment completed successfully.`;
        } else if (buildStatus === 'FAILED') {
            message = `❌ Failed deployment to ${branchName}!\n` +
                `⚠️ The build or deployment encountered issues.\n\n` +
                `Build Logs:\n${buildLogs || 'No logs available'}`;
        } else {
            console.log(JSON.stringify({
                ...logInfo,
                event: 'skip_notification',
                reason: 'build_in_progress'
            }, null, 2));
            return;
        }
 
        const params = {
            Message: message,
            TopicArn: topicArn
        };
 
        try {
            await sns.publish(params).promise();
            console.log(JSON.stringify({
                ...logInfo,
                event: 'notification_sent',
                message,
                status: 'success'
            }, null, 2));
        } catch (error) {
            console.error(JSON.stringify({
                ...logInfo,
                event: 'notification_error',
                error: {
                    message: error.message,
                    code: error.code,
                    statusCode: error.statusCode
                },
                status: 'error'
            }, null, 2));
        }
    } else {
        console.log(JSON.stringify({
            ...logInfo,
            event: 'skip_notification',
            reason: 'non_notification_branch'
        }, null, 2));
    }
};
 
run();
  3. Note const notificationBranches = ['main', 'dev']; Feel free to change this to the branches you want to get deploy notifications for.
  4. Make sure to update your dependencies in package.json to include latest aws-sdk.
  5. Commit and push your changes to the branch you want to deploy.

Test

Amplify should now be executing the post-build.js script after any deployment is complete. Check your email inbox for notifications when deploying the branches you set. If you don't receive an email, double-check the SNS topic subscription, the SNS_TOPIC_ARN environment variable, and the script for any errors.

Known Issues

Resolve Auto unsubscribe issue (Gmail)

If you're finding that you're automatically unsubscribing but don't know why, you should enable authentication to unsubscribe. See this AWS Post on how to do this. (opens in a new tab)

© Matthew Cordaro.RSS