The ZEIT Now for GitHub integration automatically deploys your GitHub projects with ZEIT Now, providing Preview Deployment URLs, and automatic Custom Domain updates.

ZEIT Now for GitHub deploying a pull request automatically.

Connecting with GitHub

Link your GitHub account with your personal account or team on ZEIT Now from your dashboard by clicking "Import Project" followed by "From Git Repository". Then, click "Install Now for GitHub".

The "You own the Repository" section with a prompt to install ZEIT Now for GitHub.

Once you have authorized the GitHub integration, you will be redirected back to the "Import Git Repository" page where you can import a project from an existing repository by clicking the "Import Project from GitHub" button.

ZEIT Now for GitHub installed and ready to set up a project.

For more information on deploying projects, read the ZEIT Now introduction documentation.

Change or Disconnect from your GitHub Repository

If you’d like to:

  • Change the GitHub repository your project is connected to
  • Disconnect your project from your GitHub repository

You can do so from the "Git Integration" fieldset on Project Settings.

More Information About ZEIT Now for GitHub

For more information, such as a reference for default environment variables, expand the relevant details view below.

A Deployment for Each Push

ZEIT 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 they are pushed to production.

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

Updating the Production Domain

If Custom Domains are set from a 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 been deployed to production, the previous Production Deployment from a commit will automatically be made available at the Custom Domain instantly; providing you with instant rollbacks.

Preview URLs for the Latest Changes for Each Pull Request

The latest push to any pull request will automatically be made available at a unique preview URL based on the project name, branch, and team or username. These URLs will be provided 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.

ZEIT 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 preview, from within GitHub in its own page. See this page for the ZEIT documentation as an example: 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 will provide the deployment URL to the checks that require it, for example; to a testing suite such as Checkly.

Configuring ZEIT Now for GitHub

To configure the ZEIT Now for GitHub integration, see the configuration reference for Git Integrations.

You may want to use different workflows and APIs based on Git information. To support this, ZEIT Now will deploy your app with the following built-in environment variables when deploying with ZEIT Now for GitHub.

hint: These environment variables are available at both Run Time and the Build Step.

Variable Key
Description
NOW_GITHUB_DEPLOYMENT
An indicator for whether the app was deployed by ZEIT Now for GitHub.
NOW_GITHUB_ORG
The GitHub organization that owns the repository the deployment is triggered from.
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 deployment was made from.
NOW_GITHUB_COMMIT_SHA
The sha of the commit the deployment was triggered by.
NOW_GITHUB_COMMIT_AUTHOR_LOGIN
The username belonging to the author of the commit that the project was deployed by.
NOW_GITHUB_COMMIT_AUTHOR_NAME
The name belonging to the author of the commit that the project was deployed by.

We require some permissions through our Now for GitHub integration. Below are listed the permissions required and a description for what they are used for.

Repository Permissions

Repository permissions allow us to interact with repositories belonging to or associated with (if permitted) the connected account.

Permission
Read
Write
Description
Administration
Y
Y
Allows us to create repositories on the user's behalf.
Checks
Y
Y
Allows us to add checks against source code on push.
Contents
Y
Y
Allows us to fetch and write source code for new project templates for the connected user or organization.
Deployments
Y
Y
Allows us to synchronize deployment status between GitHub and the ZEIT infrastructure.
Pull Requests
Y
Y
Allows us create deployments for each Pull Request (PR) and comment on those PR's with status updates.
Issues
Y
Y
Allows us to interact with Pull Requests as with the Pull Requests permissions due to GitHub requiring both for access.
Metadata
Y
N
Allows us to read basic repository metadata to provide a detailed dashboard.
Web Hooks
Y
Y
Allows us to react to various GitHub events.
Commit Statuses
Y
Y
Allows us to synchronize commit status between GitHub and ZEIT.

Organization Permissions

Organization permissions allow us to offer an enhanced experience through information about the connected organization.

Permission
Read
Write
Description
Members
Y
N
Allows us to offer a better team onboarding experience.

User Permissions

User permissions allow us to offer an enhanced experience through information about the connected user.

Permission
Read
Write
Description
Email addresses
Y
N
Allows us to associate an email with a GitHub account.
Note: We use the permissions above in order to provide you with the best possible deployment experience. If you have any questions or concerns about any of the permission scopes, please reach out tosupport@zeit.co.

To disconnect your personal account or team on ZEIT Now from GitHub, take the following steps:

First, click here to go to the Settings page on GitHub.

Then, if you've installed ZEIT Now for your personal GitHub account, click on Applications.

Application Settings on GitHub.

Or, if you've installed ZEIT Now for your organization GitHub account, first click on the organization name:

Organization Settings on GitHub.

Then, click on Installed GitHub Apps:

Organization Application Settings on GitHub.

Uninstall ZEIT Now

Then, find the "Now" application and select the Configure button next to it.

Configure ZEIT Now on GitHub.

Finally, scroll to the bottom of the page and click Uninstall.

Uninstall ZEIT Now from GitHub.

After disconnecting, you can always reconnect your ZEIT Now account to a GitHub account again.