​​Vercel allows for automatic deployments on every branch push and merges onto the Production Branch of your GitHub, GitLab, and Bitbucket projects.

Using Git with Vercel provides the following benefits:

The easiest way to use Git 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.

Deploying a Git Repository

Setting up your GitHub, GitLab, or Bitbucket repository on Vercel is only a matter of clicking the "New Project" button on the top right of your dashboard and following the steps.

After clicking it, you'll be presented with a list of Git repositories that the Git account you've signed up with has write access to.

A list of Git repositories your Git account has access to.

To select a different Git namespace or provider, you can use the selector on the top left of the section.

Selecting a different Git namespace or provider.

Alternatively, you can also:

  • Select a third-party Git repository by clicking on "Import Third-Party Git Repository" on the bottom of the section.
  • Select one of our pre-built templates from the section on the right.

After you've selected the Git repository or template you want to use for your new project, you will be presented with a list of Personal Vercel Accounts and Vercel Teams you can deploy it to.

Selecting a Personal Vercel Account or Vercel Team to deploy to.

After having made your choice, click "Continue".

If you've selected a Git repository that you have write access to, you're all set and the next page will let you create a new Project and deploy your code.

If you've selected a third-party Git repository or template, however, a different page will invite you to create a new Git repository. The third-party Git repository or template will then be cloned there.

Selecting a Git provider to clone a third-party Git repository or template to.

Once the Project has been created, you will be redirected to the Project's page on your dashboard. Congratulations!

Deploying Private Git Repositories

As an additional security measure, commits on private Git repositories (and commits of forks that are targeting those Git repositories) will only be deployed if the commit author also has access to the respective project on Vercel.

Depending on whether the owner of the connected Vercel project is a Personal Account or a Team, the behavior changes as mentioned in the sections below.

This only applies to commit authors on GitHub organizations, GitLab groups and non-personal Bitbucket workspaces. It does not apply to collaborators on personal Git accounts.

For public Git repositories, a different behavior applies.

Using Teams

In order to deploy commits under a Vercel Team, the commit author must be a member of the Team that contains the Vercel project that is connected to the Git repository.

If the commit author is not a member, the Deployment will be prevented and a request to join the Team can be issued by 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.

Using Personal Accounts

In order to deploy commits under a Personal Vercel Account, the commit author must be the owner of the Personal Account that contains the Vercel project that is connected to the Git repository. This is determined through comparing the Login Connections defined in the Personal Account with the commit author.

For cases in which the commit author is not the owner of the destination Personal Account, the Deployment will be prevented and a recommendation for transferring the project to a Vercel Team will be displayed on the Git provider.

After having transferred the project to a Vercel Team, commit authors can easily be added as members of that Team and will see the behavior mentioned in the section above applied for them whenever they commit.

Deploying Forks of Public Git Repositories

When you receive a pull request from a fork of your repository that includes a change to the vercel.json file or the project has Environment Variables, Vercel will require authorization from you or a Team Member to deploy the pull request.

This behavior protects you from leaking sensitive project information.

You can disable Git Fork Protection in the Security section of your Project Settings.

When a public repository is forked, commits from it will usually deploy automatically. However, if the vercel.json file changed, a Team Owner on Vercel has to authorize the Deployment. This is a security measurment that ensures changes to Environment Variables and other configuration properties are reviewed before a Deployment is created. A link to authorize the Deployment will be posted as a comment on the Pull Request.

The authorization step will be skipped if the commit author is already a Team Member on Vercel.

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 page in the Project Settings, you can change your Production Branch.

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.

Preview Branches

While the Production Branch (mentioned above) is a single Git branch that contains the code that is served to your visitors, Preview Branches are all the Git branches that are not the Production Branch.

For example, if your Production Branch is main, then all the Git branches that are not main are considered Preview Branches. That means there can be many Preview Branches, but only a single Production Branch.

Preview Branches, like the name already suggests, are used for previewing changes before presenting them to your visitors (merging them into Production).

By default, every Preview Branch automatically receives its own Domain similar to the one shown below, whenever a commit is pushed to it:

project-git-branch-team.vercel.app

Additionally, any Environment Variables defined for the Preview Environment are applied.

Once you're happy with your changes, you would then merge the respective Preview Branch into your Production Branch.

Multiple Preview Phases

For most use cases, the default Preview behavior mentioned above is enough.

If you'd like your changes to pass through multiple phases of previewing instead of just one, you can accomplish it like so:

Domains and Environment Variables can both be assigned to specific Preview Branches on their individual settings pages. For Domains, it can be done like this and for Environment Variables like this.

For example, you could create a phase called "Staging" where you can accumulate Preview changes before merging them onto Production by following these steps:

  1. Create a Git branch called "staging" in your Git repository.
  2. Add a Domain of your choice (like "staging.example.com") on your Vercel project and assign it to the "staging" Git branch like this.
  3. Add Environment Variables that you'd like to use for your new Staging phase on your Vercel project like this.

Afterwards, you can push to the "staging" Git branch to update your Staging phase and it will automatically receive the Domain and Environment Variables you've defined.

Once you're happy with your changes, you would then merge the respective Preview Branch into your Production Branch. However, unlike with the default Preview behavior, you'd then keep the branch around instead of deleting it, so that you can push to it again in the future.

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 for a Deployment via Git.

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

Vercel CLI should always be invoked from the monorepo root, not the subdirectory.

First, run vercel link to select the Vercel Project (you can only link to one at a time). Once linked, subsequent commands such as vercel dev will use the selected Vercel Project. To switch to a different Project in the same monorepo, run vercel link again and select the new Project.

Alternatively, you can use git clone to create multiple copies of your monorepo in different directories and link each one to a different Vercel Project.

In the future, this workflow piece will be improved drastically. In the meantime, we strongly suggest using Git to deploy 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.

Note: Check out this Support Article for further examples and information.

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.

Vercel CLI should always be invoked from the monorepo root, not the subdirectory.

First, run vercel link to select the Vercel Project (you can only link to one at a time). Once linked, subsequent commands such as vercel dev will use the selected Vercel Project.

To switch to a different Project in the same monorepo, run vercel link again and select the new Project.

Alternatively, you can use git clone to create multiple copies of your monorepo in different directories and link each one to a different Vercel Project.

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

Vercel CLI will accept Environment Variables instead of Project Linking, which can be useful for deployments from CI providers. For example:

VERCEL_ORG_ID=team_123 VERCEL_PROJECT_ID=prj_456 vercel

Learn more about Vercel CLI for custom workflows.


Last Edited on July 23rd 2021