​​Vercel provides integrations for your GitHub, GitLab, and Bitbucket projects, allowing for automatic deployments on every branch push and merge to the Production Branch.

The Vercel Git Integrations provide the following benefits:

The easiest way to use a Git Integration is to think of your main branch as production. Every time a pull/merge request is made to that branch, Vercel will create a unique deployment, allowing you to view the changes in a preview environment before merging.

In this case, main is the Production Branch. When merging to the Production Branch, a Production Deployment is made, making the latest changes available to assigned custom domains automatically.

You can choose to use a different branch as the Production Branch.

Available Integrations

Click any Git Integration from the list below to skip to its section:

Quick Installation

You can install any Git Integration directly from your dashboard by clicking "Import Project" followed by "Import Git Repository". Then enter the URL of your GitHub, GitLab, or Bitbucket repository to connect and import it.

Installing the Git Integration for a Git provider of your choice.

Deploying Private Git Repositories

In order to deploy commits from a private Git Repository (or a fork of a private Git Repository) under a Team, the commit author has to be a member of the Team on Vercel (even if the commit author is a bot).

If the commit author is not a member, the Deployment will be prevented and a request to join the Team will automatically be issued for the commit author. After that, the owners of the Team will be notified and can either accept or decline the membership request on the "Members" page in the Team Settings.

Declining the request will leave the commit undeployed. If the commit author gets accepted as a member of the Team, however, their most recent commit will resume to be deployed to Vercel automatically.

Commit authors will automatically be considered a part of the Team on Vercel if one of the existing members connected their Personal Account on Vercel with the Git account that created the commit.

Production Branch

A Production Deployment will be created each time you merge to the Production Branch.

Default Configuration

When you create a new Project from a Git repository on Vercel, the Production Branch will be selected in the following order:

  • The main branch.
  • If not present, the master branch (more details).
  • [Only for Bitbucket] If not present, the "Production Branch" setting of your Git repository is used.
  • If not present, the Git repository's default branch.

Customizing the Production Branch

On the Git Integration page in the Project Settings, you can change your Production Branch to be one of the following:

  • The main branch.
  • The Git repository's default branch (for Bitbucket, the Git repository's "Production Branch" setting is considered).
  • Any other custom branch of your choice.

Whenever a new commit is then pushed to the branch you configured here, a Production Deployment will be created for you.

Configuring the Production Branch of your Project.

Monorepos

If you'd like to deploy multiple different directories within the same Git repository, you can do so by creating a separate Project for each directory and configuring the Root Directory setting for it.

The easiest way to achieve this is by importing your Git repository multiple times and selecting a different Root Directory every time – until one Project was created for each of the relevant directories.

Selecting a Root Directory for one of your new Projects.

Once you've created a separate Project for each of the directories within your Git repository, every commit will issue a Deployment for all connected Projects and display the resulting URLs on your pull requests and commits:

An example of Deployment URLs provided by a Git Integration.

The amount of Vercel Projects that can be connected with the same Git repository is limited depending on your plan. To increase this limit, please contact our Sales Team.

Using Monorepos with Vercel CLI

Because it's only possible to link a single Vercel Project when running the vercel command, we recommend cloning your Git repository multiple times and then running vercel for each one to deploy them.

The same applies to the vercel dev command (local Development).

In the future, this workflow piece will be improved drastically. In the meantime, we strongly suggest using one of our Git Integrations instead of Vercel CLI.

Ignoring the Build Step

Pushing a commit to your monorepo will create a Deployment for each of the connected Vercel projects.

If you want to abort the Build Step for certain projects if their files didn't change, you can do so with the Ignored Build Step project setting.

Monorepo FAQ


Whether or not your deployments are queued depends on the amount of Concurrent Builds you have available. Personal accounts are limited to 1 Concurrent Build, while teams can customize the amount on the "Billing" page in the team settings.

Learn more about how to adjust your Concurrent Builds here.

After having set up your monorepo as described above, each of the directories will be a separate Vercel project, and therefore be available on a separate domain.

If you'd like to host multiple projects under a single domain, you can create a new project, assign the domain in the project settings, and proxy requests to the other upstream projects. The proxy can be implemented using a `vercel.json` file with the rewrites property, where each `source` is the path under the main domain and each `destination` is the upstream project domain.

Pushing a commit to a Git repository that is connected with multiple Vercel projects will result in multiple deployments being created and built in parallel for each.

To access source files outside the Root Directory (which enables Yarn & Lerna Workspaces), enable the "Include source files outside of the Root Directory in the Build Step" option in the Root Directory section within the project settings.

Vercel projects created after August 27th 2020 23:50 UTC have this option enabled by default.

If you're using Vercel CLI, at least version 20.1.0 is required.

Because Vercel CLI only allows for linking a single Vercel project, you currently need to clone your Git repository multiple times (once per directory you want to deploy or develop) and then link a project for each.

Use at least version 20.1.0 of Vercel CLI to ensure you can take advantage of the option for accessing source files outside the Root Directory (mentioned in a section above).


Last Edited on August 28th 2020