How do I get a notification when my Vercel deployment fails?

My team was working on a project together and getting lots of ‘bot’ emails from our GitHub integration to Vercel. At least, we were getting emails when the build and deploy succeeded to Vercel.

But what about when the deployment fails?

Everything looked fine locally, the site was working, but after a few days of not getting email notifications we realized that Vercel was no longer deploying. Lots of errors in the logs. We had no idea! How do we get notified when something goes wrong on the Vercel side?

This is “normal”.

When you have Vercel hooked into GitHub, a successful deployment triggers a comment (by the Vercel bot) back to the commit that caused the deployment. This is where the ‘success’ message goes, and why we were getting notifications. It wasn’t Vercel sending us the notification, it was GitHub letting us know that there was a comment on the commit.

It was confirmed for me by the Vercel team that it is entirely expected that Vercel does not put a comment back onto the Commit when there is a failure. What can you do out of the box?

1. You can see that the GitHub status checks are “all failed” on GitHub itself.
2. You can go to /deployments on your GitHub repo and see all the Vercel deployment attempts.
3. You can click through a given deployment to go to the Vercel side and find out why it failed.

But still… there is no notification of a failure. And I wanted one!

This seems like such a basic continuous integration scenario I couldn’t believe this hadn’t been covered somewhere. Somebody must be triggering deployments and figuring they’ll get an email if the ‘build’ goes red? Netlify has a whole slew of notifications that happen around site deploys.

I reached out on the Vercel GitHub discussions board, but got no responses. However, thanks to some helpful folks at Vercel who responded to an email, I was able to get some guidance.

GitHub Actions to your rescue

I was recommended to look into GitHub actions to run custom workflows when specific deployment states occur. You can specify which state to run a specific job on, and then invoke the GitHub API.

SIDE NOTE: Due to restrictions that can occur with private repos and your organization account, you may not have access to GitHub Actions. I had to work in a public repo to get this to work for me.

So, I decided to invoke the API for adding comments on a commit to mirror what the Vercel bot was doing on a success. (View on GitHub)

#Triggered for deployment status changes
name: Deployment Failure notification
on: [deployment_status]

jobs:
  add-failure-comment:
    name: Add a comment to the commit that caused the failure
    if: github.event.deployment_status.state == 'failure'
    runs-on: ubuntu-latest

    steps:
      - name: Add commit comment - failure
        run: |
          curl -L -X POST \
          --url https://api.github.com/repos/${{ github.repository }}/commits/${{ github.sha }}/comments \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "body": "Deployment has failed."
            }'

The important bits

The if statement here ensures that we tap into the deployment state and only do this on a failure:

   if: github.event.deployment_status.state == 'failure'

The curl block invokes the GitHub API, specifically the one for commit comments.

   curl -L -X POST \
         --url https://api.github.com/repos/${{ github.repository }}/commits/${{ github.sha }}/comments \

The body part of the data parameter is the content that will be put into the commit:

   --data '{
            "body": "Deployment has failed."
            }'

And when a deployment fails it adds a comment like this:

Getting a notification

Alrighty, at this point, I had a comment being added to a commit… but I said I wanted a notification and that usually means people getting an email when the deployment fails, right?

The reason using the GitHub commit comment is nice is that it ties right into GitHub’s normal notifications configuration. You can update your settings on how you get notifications for things that happen on GitHub. In the Email notification preferences section you can configure what you want to get emails about.

So with this comment being added to the commit, you’ll get a notification when you break the deployment!

Downloading the code

I have made the code available in a repo. If I think of other helpful actions, I’ll add those there too:

• Vercel Deployment Failure Notification (jst-cyr GitHub repo)

Things I read when trying to figure this out:

• “How to get notified when Vercel deployment gets failed? (from NextJS Reddit, 2021-06-08)
• Disable build email? (from Vercel GitHub, 2020-05-05)
• Vercel API docs – List deployments
• Vercel for GitHub documentation
• Vercel ‘Git’ configuration
• Netlify site notifications
• Commit Comment repo (by Peter Evans)
• Workflow commands for GitHub Actions (GitHub docs)
• Getting started with the REST API (GitHub docs)
• Working with comments (GitHub docs)
• Create a commit comment (GitHub API reference)