The Now for GitHub integration automatically deploys your GitHub projects with ZEIT Now, providing staging URLs and automatic production domain updates.

The Now for GitHub integration features:

  • Deploys every push in branches and pull requests to preview changes live
  • Updates production domains with the most recent changes from the master branch
  • Instant rollbacks for production domains when reverting changes

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 ZEIT 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 to be deployed with ZEIT Now.

Default Behavior

A Deployment for Each Push

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

With each new push, if Now is already building a previous commit, Now will cancel that current build to start the most recent commit so that you always have the latest changes deployed as quickly as possible.

Updating the Production Domain

If production domains are set from the project domains dashboard, pushes and merges to the default branch (commonly "master") will be made live to those domains with the latest deployment made with a push.

If you decide to revert a commit that has already updated a product domain, the previous commit's deployment will automatically be made available at the production domain instantly; providing you with instant rollbacks.

Staging URLs for the Latest Changes for Each Pull Request

The latest push to any pull request will automatically be made available at a unique staging URL based on the project name, branch, and team or username. These URLs will be given through a comment on each pull request.

Deployment Authorizations for Forks

If you receive a pull request from a fork of your repository and there is either a change to the now.json file or there are secrets used in your project; Now will require an authorization from you or a member of your team to deploy the pull request.

This behavior protects you and your project from a leak of sensitive information.

Extending Your GitHub Workflow

Now for GitHub uses the deployment API to bring you an extended user interface both in GitHub, when showing deployments, and Slack, if you have notifications setup using the Slack GitHub app.

You will see all of your deployments, production or staging, from within GitHub in its own page. See the page for this very documentation: https://github.com/zeit/docs/deployments

Due to using GitHub's Deployments API, you will also be able to integrate with other services through GitHub's checks. Now for GitHub will provide the deployment URL to the checks that require it, for example; to a testing suite such as Ghost Inspector.

The checks UI from GitHub containing ZEIT Now and Ghost Inspector.

Configuration

Disabling Production Domain Updates

To prevent Now from automatically updating production domains, use the following configuration option in a now.json file:

{
  "github": {
    "autoAlias": false
  }
}

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

Disable Commenting with Silent Mode

To prevent Now from commenting on pull requests and commits, use the following configuration option in a now.json file for the repository you want to stop this behavior in.

Note: Although Now will stop commenting, it will not stop deploying the latest updates. For this configuration option, see disabling Now for GitHub
{
  "github": {
    "silent": true
  }
}

Disable Auto Job Cancellation

To prevent Now from canceling in-progress builds to prioritize building newer commits, use the following configuration option in a now.json file for the repository that this behavior 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, ZEIT Now will deploy your app with following built-in environment variables.

Variable Key
Description
NOW_GITHUB_DEPLOYMENT
An indicator for whether the app was deployed by Now for GitHub.
NOW_GITHUB_ORG
The GitHub organization who the app belongs to.
NOW_GITHUB_REPO
The origin repository of the app.
NOW_GITHUB_COMMIT_ORG
The organization of which the commit belongs. For example, when submitting a pull request from a forked repository.
NOW_GITHUB_COMMIT_REPO
The repository of which the commit belongs. For example, when submitting a pull request from a forked repository.
NOW_GITHUB_COMMIT_REF
The branch that the app was deployed using.
NOW_GITHUB_COMMIT_SHA
The sha of the commit the app was deployed using.
NOW_GITHUB_COMMIT_AUTHOR_LOGIN
The username belonging to the author of the commit that the project was deployed using.
NOW_GITHUB_COMMIT_AUTHOR_NAME
The name belonging to the author of the commit that the project was deployed using.
Note: You can access these as build environment variables also.