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:
- Preview Deployments for every push.
- Production Deployments for the most recent changes from the Production Branch.
- Instant rollbacks when reverting changes assigned to a custom domain.
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.
To select a different Git namespace or provider, you can use the selector on the top left of the section.
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.
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.
Once the Project has been created, you will be redirected to the Project's page on your dashboard. Congratulations!
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 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.
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.
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:
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 Git 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.