To deploy on Vercel, you need to create a Project. A Project groups deployments and custom domains. Each project can receive deployments from GitHub, GitLab, Bitbucket, or Vercel CLI.

Creating a Project

You can create a new project from the Vercel Dashboard by clicking on the New Project button.

Creating a new project from the Vercel Dashboard.

You can either import from an existing Git repository or use one of our templates.

Project Settings

To edit project settings, choose a project from the dashboard:

Selecting the project from the Vercel Dashboard.

Then, select the Settings tab:

Selecting the Settings tab from the Project Overview page.

General Settings

Project Name

Project names can only consist of up to 100 alphanumeric lowercase characters. Hyphens can be used in between the name, but never at the start or end.

Build & Development Settings and Root Directory

You can edit build and development settings as well as the root directory settings. Check out our Build Step documentation to learn more.

Environment Variables

You can configure Environment Variables directly from Project Settings. Check out the Environment Variables documentation to learn more.

Install Command

Learn more about the default Install Command (and how to use the Project Settings to define a custom one) in our Build Step documentation.

Only applied starting from your next deployment

As with other project settings, the changes you make to this setting will only be applied starting from your next deployment.

Note: When you toggle this setting, none of your existing deployments will be affected. If you’d like to make the source code or logs private on your existing deployments, the only option is to delete them.

Node.js Version

Learn more about how to customize the Node.js version of your project on the Runtimes documentation.

Custom Domains

You can add custom domains for each project. Check out our Custom Domains documentation to learn more.

Git

To edit your project’s Git settings, select the Git menu item from your project settings page.

Selecting the Git menu item from the project settings page.

If you haven’t connected Vercel with GitHub, GitLab, or Bitbucket yet, you can do so from here.

Selecting a Git Provider.

Next, find the Git repository by choosing the respective Git namespace from the dropdown and searching for the name of the Git repository. Then, click on the Connect button to connect your project to the Git repository.

Choosing a GitHub repository to connect to your project.

Once your project has been connected to a Git repository, you will see it from the settings.

Your project has been connected to the GitHub repository.

If you’d like to disconnect your project from a Git repository, click on the Disconnect button.

Deploy Hooks

Vercel supports deploy hooks, which are unique URLs that accept HTTP POST requests and trigger deployments. Check out our Deploy Hooks documentation to learn more.

Security Settings

To edit your project’s security settings, select the Security menu item from your project settings page.

Selecting the Security menu item from the Project Settings page.

Ignored Build Step

By default, Vercel will issue a new Deployment with Build (unless the Build Step is skipped) for every commit to your connected Git repository.

Each commit in Git is assigned a unique hash value commonly referred to as SHA. If the SHA of the commit was already deployed in the past, no new Deployment is created. In that case, the last Deployment matching that SHA is returned instead.

To customize the behavior for your Git repositories, you can enter a command in the Ignored Build Step section of the Git page, which will then determine whether or not a new Build needs to be issued:

Specify the Git repository for your project.

Each commit in Git is assigned a unique hash value commonly referred to as SHA. If the SHA of the commit was already deployed in the past, no new Deployment is created. In that case, the last Deployment matching that SHA is returned instead.

While the Deployment is in the BUILDING state, the command you've entered in the Ignored Build Step section will be run. If the command exits with code 1, the Build will continue as usual. If the command exits with code 0, however, the Build is immediately aborted and the Deployment state is set to CANCELED.

The command is executed within the Root Directory.

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

Logs and Source Protection

By default, the paths mentioned below can only be accessed by you and members of your Vercel Team. Turning off Logs and Source Protection will make them publicly accessible.

  • /_src: Displays the source code and build output.
  • /_logs: Displays the build logs.

This setting is overwritten when a Deployment is created using Vercel CLI with the --public option or the public property in vercel.json.

Warning: Do not edit this setting if you don’t want your source code or logs to be publicly accessible.

Note: For Deployments created before July 9th, 2020 at 7:05 AM (UTC), only the Project Settings is considered for determining whether the Deployment's Logs and Source are publicly accessible or not. It doesn't matter if the --public flag was passed when creating those Deployments.

Git Fork Protection

If 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 this protection in the Security section of your Project Settings.

Warning: Do not disable this setting until you review Environment Variables in your Project as well as vercel.json in your source code.

Password Protection

Note: This feature is not available for personal accounts. Only teams can opt into this feature, and the team must be on the Pro or Enterprise plan.

By using Password Protection, you can ensure that visitors of your Preview Deployments must enter a password in order to gain access.

Teams can opt into using this feature by enabling it from the "Optional" badge and paying $150 per month. Once you opt in, you can use it across other projects in the same team:

Enabling Password Protection.

Warning: After enabling the feature, one month has to pass before it can be disabled again.

Protecting Preview Deployments

To use this feature, turn on the toggle and specify the visitor password.

Turning on the toggle and specifying the visitor password.

After clicking Save, all Preview Deployments (existing and future ones) of this project will immediately be protected with a password. If you try to access the page, you’ll be presented with this screen:

Password is required.

After entering the password, the visitor will be redirected to the deployment. Also, a cookie will be set in the visitor’s browser, giving them access to all Preview Deployments of the project.

Protecting Production Deployments

Protecting Production Deployment.

To protect Production Deployments in addition to Preview Deployments, check “Also protect my Production Deployment" and click Save.

Details

  • If you change the password, visitors who have previously entered the password (and therefore have the cookie set) will need to re-enter the password.
  • If you disable the protection, all existing deployments of the project will become unprotected.
  • If you disable the protection and then enable it, visitors who have the cookie set will continue to be able to access the deployments without re-entering the password.
  • You can use Password Protection in conjunction with SSO Protection.

To bypass the protection programmatically, please read this.

Disabling the Feature

To opt out from this feature, you can do so from your team’s SettingsBilling page. Click Edit next to Password Protection and follow the instructions:

Disable the Password Protection Feature.

SSO Protection

Note: This feature is not available for personal accounts. Teams can opt into this feature by contacting our sales team.

By using SSO Protection, you can ensure that visitors of your Preview Deployments must log in with a personal Vercel account that is a Team Member to gain access.

Teams can opt into using this feature by clicking the "Optional" badge and contacting our sales team.

Enabling SSO Protection.

Protecting Preview Deployments

Once your team has access to the feature, turn on the toggle to enable it.

Turning on the toggle.

After clicking Save, all Preview Deployments (existing and future ones) will immediately require logging in with a personal Vercel account, and the account must be a Team Member. If you try to access the page, you’ll be presented with this screen:

Logging in with Vercel is required.

If a visitor logs in with a personal Vercel account that’s a Team Member, the visitor will be redirected to the deployment. Also, a cookie will be set in the visitor’s browser, giving them access to Preview Deployments.

Note: If you’ve also enabled Password Protection, the login UI will look like this:

Logging in using a password or with Vercel is required.

Protecting Production Deployments

Protecting Production Deployment.

To protect Production Deployments in addition to Preview Deployments, check “Also protect my Production Deployment" and click Save.

Details

  • If you disable the protection, all existing deployments of the project will become unprotected.
  • If you disable the protection and then enable it, visitors who previously logged into the deployment with Vercel will continue to be able to access the page without logging in again.
  • If an account is removed from the team, then that account can no longer be used to access the deployment. The cookie will also become invalid.
  • You can use SSO Protection in conjunction with Password Protection.

Deleting a Project

Warning: Deleting your project will also delete the deployments and domains within it. If you have any deployments that are assigned to a custom domain and do not want them to be removed, make sure to deploy and assign them to the custom domain under a different project first.

To delete a project, choose a project from the dashboard:

Selecting the project from the Vercel Dashboard.

Then, select the Settings tab:

Selecting the Settings tab from the Project Overview page.

Next, select Advanced from the menu.

Selecting the Advanced menu item from the Project Settings page.

You’ll see the Delete Project section. Confirm that you'd like to delete the project and click the Delete button.

The Delete Project section.

Transferring a Project

Projects can be transferred between Vercel Accounts with zero downtime and no workflow interruptions. This is particularly useful when upgrading from a Hobby Personal Account to a Pro Team.

Restrictions

  • You must be an owner of a Team to move a Project away from that Team.
  • Transferring a Project away from an Enterprise Team may require additional steps, so please contact Support to move the Project with zero downtime.

Downtime

Your Project will not experience any downtime during a transfer! Your Project Domains will remain fully operational throughout the entire process.

What is Transferred?

Deployments, Aliases, Domains (more details), and the Project's configuration are transferred from the original Project.

Environment Variables are copied to the target Team. If an Environment Variable is associated to a Secret and the Secret exists on the target Team, that Secret will be renamed.

Environment Variables defined in the env and build.env configuration of vercel.json will not be transferred. They must be migrated to Environment Variables in the Project Settings or configured again on the target Team after the transfer is complete.

Integrations associated with your Project will not be transferred. They must added again after the transfer is complete.

When transferring to a Vercel Team, you may choose to enable additional paid features on the target Team to match the features of the origin account. These include:

Transferring Domains

Project Domains will automatically be transferred to the target Team by delegating access to Domains, if necessary.

For example, if your Project uses the Domain example.com, the Domain will be moved to the target Team. The target Team will now be billed as the primary owner of the Domain if the Domain was purchased through Vercel.

If your Project uses the Domain blog.example.com, the Domain blog.example.com will be delegated to the target Team, but the root Domain example.com will remain on the origin Vercel scope. The origin Vercel scope will remain the primary owner of the Domain, and will be billed as usual if the Domain was purchased through Vercel.

If your Project uses a Wildcard Domain like *.example.com, the Wildcard Domain will be delegated to the target Team, but the root Domain example.com will remain on the origin Vercel scope.

Starting a Transfer

To begin transferring a Project, choose a project from the dashboard:

Selecting the project from the Vercel Dashboard.

Then, select the Settings tab:

Selecting the Settings tab from the Project Overview page.

Next, select Advanced from the menu.

Selecting the Advanced menu item from the Project Settings page.

Here, you'll see the Transfer Project section:

The Transfer Project section.

Click Transfer to begin the Transferring flow.

Target Account

Select the Vercel Account you wish to transfer the Project to. You can also choose to create a new Team.

Choosing an account to transfer the Project to.

If the target Vercel Account does not have a valid payment method, you must add one before transfering your Project to avoid any interruption in service. If a valid payment method is added to a Team on a Pro Trial Plan, the Pro Trial Plan will be upgraded to the Pro Plan immediately.

Additional Features

Note: This only applies when transferring away from a Team.

When transferring between Teams, you may be asked whether you want to add additional features to the target Team to match the origin Team's features. This ensures an uninterrupted workflow and a consistent experience between Teams.

Adding these features is optional.

Optionally adding additional paid features to the target Team.

Confirm Transfer

This final step lists all of the Project Domains, Aliases, and Secrets that will be transferred. You can also choose a new name for your Project. By default and if possible, the existing name is re-used. You may need to provide a new name if the target Vercel Account already has a project with the same name.

Note: The original Project will be hidden when initiating the transfer, but you will not experience any downtime.

Reviewing the Project data that will be transferred to the target Vercel Account, and choosing a new Project name.

After reviewing, click Transfer to initiate the Project transfer.

Transfer in Progress

You will be redirected to the newly created Project on the target Vercel Account with in-progress indicators.

Project pages will indicate that the transfer is in progress.

While a transfer is in progress, you may not:

  • Create new deployments for the Project
  • Modify any Project settings, including Domains, Secrets, and Integrations
  • Delete the Project

Transfer Completed

Depending on the amount of associated data, transferring a Project may take between 10 seconds and 10 minutes.

When the transfer completes, the initiator of the transfer and the owners of the target Team will be notified by email.

You can now use your Project as normal!