After announcing our new Vercel for GitHub integration we have welcomed thousands of new users and organizations. Today, we want to take a deeper look at how it works. In particular, we will be discussing: Error Handling.
Vercel for GitHub deploys code from GitHub pull requests, with this in mind, there's a chance that the code is not valid for Vercel to deploy. Let's take a look at how Vercel for GitHub goes through the deployment process and handles errors along the way.

What is Vercel for GitHub?

Vercel makes deploying your apps as simple as one command from your terminal. Still, we aim to go even further with making deployments easier. This is where Vercel for GitHub comes in.
If you are in the habit of making pull requests, you are most of the way there. Installing Vercel for GitHub and adding it to your repositories, then creating a vercel.json file will enable deployments on all new pull requests and any changes that are added to PRs. It's as simple as that! Live deployments of your app, with your changes whenever you make them.

Going Behind the Scenes

GitHub gives us a fantastic platform to create a new flow for deployments, but deploying your apps is where the ball comes into our court.

The Process

After installing Vercel for GitHub to your account or organization's repositories, and then adding a vercel.json to those repositories, our job can begin to automatically deploy your pull requests.
The flow begins when you either create or push to a pull request, we will attempt to start deploying your app including the latest changes in your PR. At this stage of the deployment creation process, there are two possible paths the deployment can take.

1. Failing

The first thing we do is check to see if the code is valid for the deployment process to continue. If our validations fail with your code, the Vercel app will write a comment telling you what happened and the Vercel app will report the status as "failed" in the checks section of the PR UI.
We'll explore what kind of errors can happen, and how we handle them, below.
Note: These validations check to see whether your app is valid for us to begin deployment. Other errors with your app could come later in the deployment process.

2. Success

If our validations pass, we can then continue deploying your app. Vercel will post a comment, telling you how to access your deployment first, since we give a link right away. You can access this, as the comment will say, by clicking on the icon next to the commit sha ID.

The deployment process will start like any deployment that you make from Vercel CLI. It will begin first by directing you to a deployment page on The deployment, at this point, will be in the INITIALIZING stage. In this stage, we will run any build steps necessary, save the build image, then make your app live.

Once the app is in the `READY` state, it will redirect you from to the live deployment. Otherwise, you can click the icon again to go to the live app. This link will now be shareable to everyone!

From the READY state, your app can be instantiated anywhere in the world. Learn more about this from our documentation on Global Scaling.

An in-depth look at errors

There are a few cases where Vercel for GitHub could fail when attempting to deploy your pull request code. A few of these include:
  • An empty, invalid, or missing vercel.json file
  • No npm start script in package.json for npm deployment types
  • An invalid type property inside the vercel.json

Handling errors

When you submit a pull request, we will take a look at what we need to be able to deploy your code. If we find that there is a conflict in the way of us being able to carry out a deployment, we will exit the process and report an error to you.
Let's take an invalid vercel.json file for example. This file needs to be valid JSON, at least. So containing {} within the file is enough to get Vercel started deploying. If the vercel.json file is empty or has content that isn't valid JSON, we detect this and send a comment to your pull request informing you of this.
To get a deployment to go through after an error, the problem must be resolved. If our vercel.json file has the contents /{}, for example, we need to remove the leading forward-slash in order for the file to be accepted as valid JSON. Once we make this fixing change, we can push a new commit to the pull request, which failed originally when deploying, and Vercel will try to deploy once again. This time, if there are no further errors, the deployment should proceed and go live within a matter of moments!

Pushing an invalid `vercel.json` file to a GitHub pull request.


Now that we have been through an in-depth look at how Vercel for GitHub works when handling deployments, especially in the case of errors, feel free to give it a go yourself!
Read our announcement for Vercel for GitHub for a look at more use-cases, learn more about using it, or get started!