Note: This documentation is for version 1 of the Vercel platform. For the latest features, please see the version 2 documentation. If you have yet to upgrade, see the upgrade guide.

Now for GitHub

Now for GitHub is an app for GitHub users or organizations that automatically deploys and aliases changes to repositories with Now.

The Now for GitHub integration features:

  • Deploys every push in branches and pull requests to preview changes live
  • Aliases the most recent changes from the master branch
  • Instant rollbacks when reverting changes that have been aliased

Now for GitHub providing a deployment for a GitHub pull request.

Connecting the App to Your Github Account or Organization

Now for GitHub is directly connected with your Vercel account and can be linked from within your account or team settings. Within the settings page under the "General" tab, the first section will offer for you to install Now for GitHub if it is not already installed.

The Now for GitHub installation section within the account or team general settings page.

If you are a new user signing up, this process can also be started from within the onboarding stage.

The Now for GitHub installation section within the account or team onboarding.

Clicking the "Install Now for GitHub" button will take you to GitHub where they will prompt you, if you have an account belonging to any organizations, which profile the installation should be installed with. You can pick either your GitHub account or any of the organizations you have access to.

If you are not part of any organization, you will skip straight to the repository selection.

For organizations that you have limited permissions for, GitHub will ask you to request access to install the integration. Once requested, the organization's owner will need to approve the integration.

The account or organization selection step on GitHub.

With an account or organization selected, GitHub will now ask for which repositories Now for GitHub should work with. In this step you are able to allow all repositories to be deployed or an optional set of repositories.

With the GitHub profile and repositories chosen for Now for GitHub to work with, the application will be ready to start using. The next step is to prepare the repository for Now to deploy.


Now for GitHub requires a now.json file to exist in the root of the repository to begin deploying that repository.

A now.json file is a way to configure the deployments Now will make using your code. To get started deploying from your repository, the now.json configuration does not need any specific setup, you will only need a valid JSON file. For example, you can use an empty object ({}) for the file to be valid and recognized by Now to start deploying.

With the repository correctly configured, Now for GitHub will start deploying the app.

Default Behaviour

A Deployment for Each Push

Now for GitHub will deploy every push by default. This includes pushes to any branch that includes a now.json and any pull requests made from those branches. This allows those working within the repository to preview changes made before the changes are pushed to production.

Aliasing the Default Branch

If an alias is set within the now.json file, pushes and merges to the default branch (commonly "master") will be aliased automatically and made live to those aliases with the latest deployment made with a push.

For example, the following now.json configuration will make Now for GitHub alias the most recent push to by default.

  "alias": [""]


Disabling Now for GitHub with now.json

To disable Now for a GitHub repository, use the following configuration option in the now.json file:

  "github": {
    "enabled": false

This example is of an entire now.json file with the noted configuration option to disable Now for GitHub.

Disabling Now for GitHub with this configuration option will prevent Now from deploying any push or aliasing the changes when merged to the default branch.

Disabling Auto-Aliasing

To stop Now from automatically aliasing the default branch to any alias setup within the now.json file, use the following configuration option.

  "alias": [""],
  "github": {
    "autoAlias": false

This example is of an entire now.json file with the noted configuration option to disable auto-aliasing with Now for GitHub. The file also includes an example setup alias.

Disable Commenting with Silent Mode

You can enable the silent mode and ask us to stop commenting on pull requests and commits. Even though we stop adding comments, we will continue to add commit status.

This is a per repo setting. You can enable it by adding the following configuration option to the now.json file:

  "github": {
    "silent": true

Disable Auto Job Cancellation

To stop Now from canceling in-progress builds to prioritise building newer commits, use the following configuration option in a now.json file for the repository that this behaviour should exist in.

  "github": {
    "autoJobCancelation": false

Included Environment Variables

You may want to use different workflows and use different APIs based on Git information.
In order to support that, Now will deploy your app with following built-in environment variables.

"NODE_ENV": "production",
"NOW_GITHUB_ORG": "zeit",
"NOW_GITHUB_REPO": "simple-now-app",
"NOW_GITHUB_COMMIT_REPO": "simple-now-app",
"NOW_GITHUB_COMMIT_SHA": "3019e532462d96a8113e8968102803e5ffbb9909",
Note: You can access these as build environment variables also.