Site deploys overview

Netlify enforces a strict concept of atomic deploys. If you’re used to uploading files with FTP, SSH, RSync or S3’s API, this is quite a different concept.

Instead of pushing individual files to Netlify, you always create a new deploy. Netlify will compare the new deploy with your existing deploy and determine which files have changed and need to be uploaded.

No changes go live on your site’s public URL before all changes have been uploaded. Once all the changes are ready, the new version of the site immediately goes live on the CDN.

This means deploys are atomic, and your site is never in an inconsistent state while you’re uploading a new deploy.

With FTP or S3 uploads, each file is pushed live one after the other, so you can easily get into situations where a new HTML page is live before the supporting assets (images, scripts, CSS) have been uploaded. And if your connection cuts out in the middle of an upload, your site could get stuck in a broken state for a long time.

Atomic deploys guarantee that your site is always consistent.

Files per directory limit

While Netlify doesn’t have a limit on the number of files per deploy, we do have a limit of 54,000 files per directory. If any directory within your publish directory has more than 54,000 files, your deploys will fail.

# Deploy summary

You can find a deploy summary on the detail page of any successful deploy, right above the deploy log. It allows you to quickly identify your deploy status and refer to the details in the log based on different types of information.

This summary indicates how many files have been uploaded to our CDN. It also indicates the status of site headers and redirects included in the deploy. It also indicates whether your site contains content served over insecure HTTP, known as mixed content. It also shows you how many edge functions were deployed.

When you have branch deploys enabled, the summary will inform you if the files to upload have already been uploaded by a previous deploy with the same commits. Netlify’s deployment infrastructure knows how to avoid uploading the same file twice, even between different deploys, so we get your changes ready without duplicating content. You can read more about how this works in this article about our deploying and routing infrastructure.

If the summary continually indicates that many more files were uploaded than you were expecting, your site may be taking longer to deploy than it needs to. Visit our Forums for a verified Support Guide on making the most of Netlify’s CDN cache to learn about why this might be happening and get advice about what you can do to reduce the number of files uploaded each time in order to speed up your deploys.

# Deploy log

You can find a deploy log on the detail page of every deploy. The log provides content such as:

  • details about your site’s build image, dependency caching, and Netlify Build process, including all of the standard output which comes from running your build
  • information about any Build Plugins your site may have installed and their execution
  • details about the success, failure, or cancellation of the deploy

For any successful deploy, highlights from the deploy log will be included in the deploy summary.

For failed deploys, visit our Forums for a verified Support Guide on using the log to debug your build process. Note that Netlify deletes failed and canceled deploys that are 6 months old. Learn more about automated cleanup for failed deploys.

# Share log content

Deploy logs for a site linked to a private repo are available to all site members. For a site linked to a public repo, you can control deploy log visibility to determine the privacy level.

To share deploy log content, you can copy the entire log by selecting Copy to clipboard (the clipboard icon). You can also generate a shareable URL for a single log line or a range of lines.

  • For a single log line, select the line number to highlight the line.

  • For a range of log lines, select the line number for the first log line in the range, then press shift and select the final log line number to highlight the full range.

    selected deploy log lines.

  • If needed, press esc to deselect log lines.

Once you’ve selected a line or range, copy the resulting URL from the address bar of your web browser. The URL syntax should resemble this: https://app.netlify.com/sites/SITE_NAME/deploys/DEPLOY_ID#L5-L10

# Branches and deploys

Netlify lets you control which branches in your Git repository you want to deploy.

# Definitions

  • Production branch: the Git branch that Netlify uses to build and deploy changes to your site’s main URL, such as www.yourcustomdomain.com or yoursitename.netlify.app.
  • Production deploy: a deploy from the production branch. If auto publishing is enabled, each new production deploy will update what is published at your site’s main URL.
  • Branch deploy: a deploy generated from a branch that is not your production branch. Branch deploys are published to a URL which includes the branch name as a prefix. For example, if a branch is called staging, it will deploy to staging--yoursitename.netlify.app. If you use Netlify DNS, you can enable branch subdomains, so the staging branch example would deploy to staging.yourcustomdomain.com.
  • Deploy Preview: a deploy generated from a pull request or merge request, building a preview of the site based on the latest commits. Deploy Previews are published to a URL which has the prefix deploy-preview followed by the identifier number of the pull request or merge request. For example, a Deploy Preview for pull/merge request #42 will deploy to deploy-preview-42--yoursitename.netlify.app. For more information, visit the docs on Deploy Previews.
  • Permalink: every successful build of your site also creates a deploy permalink that starts with the deploy ID number. For example: 1234abcd12acde000111cdef--yoursitename.netlify.app. The web content at this URL never changes. This is in contrast to production deploys, branch deploys, and Deploy Previews where the web content is updated when you merge or push new commits.

# Branch deploy controls

By default, Netlify deploys the site’s production branch after every change.

To generate deploys for other branches in your repository, select your site on the Sites page. Then go to Site settings > Build & deploy > Continuous Deployment > Branches, and select Edit settings. You can choose to deploy all branches (including future branches), or select individual branches you would like to deploy.

undefined

When selecting individual branches for deployment, type the name of each branch you want to deploy. You can also enter branch names you haven’t created yet.

Once you select some or all of your branches for deployment, Netlify starts monitoring those branches for updates. New commits to the selected branches generate new branch deploys. By default, new pull/merge requests against the selected branches generate new Deploy Previews.

You can control who can access your site’s branch deploys by requiring a password. Learn more at our password-protection docs.

# Deploy Preview controls

You can control who can access your site’s Deploy Previews by requiring a password to visit your Deploy Preview. Learn more at our password-protection docs.

By default, Netlify automatically builds Deploy Previews for GitHub pull requests and GitLab merge requests when the base/target branch is your production branch. If you enable branch deploys for some or all of your other branches, we’ll also build Deploy Previews for pull/merge requests against those branches. Collaboration tools available in the Netlify Drawer are enabled by default for Deploy Previews.

You can control in the UI whether or not Deploy Previews are generated for pull/merge requests. You can also enable or disable the Netlify Drawer. To change these settings, select your site and go to Site settings > Build & deploy > Continuous Deployment > Deploy Previews, then select Edit settings.

# Search engine indexing

Netlify automatically ensures that only your currently published production deploy and most recent branch deploys can be indexed by search engines. Requests to Deploy Previews, unpublished production deploys, and old branch deploys will have an X-Robots-Tag: noindex header included in the response. Depending on how you use branch deploys, you may want to prevent even your most recent branch deploys from being indexed by search engines. You can do so by configuring custom headers in your branch.

# Deploy contexts

Deploy contexts give you the flexibility to configure your site’s builds depending on the context they are going to be deployed to.

There are four predefined deploy contexts:

  • production: this context corresponds to the main site’s deployment, attached to the Git branch you set when the site is created.
  • deploy-preview: this context corresponds to the previews we build for pull/merge requests.
  • branch-deploy: this context corresponds to deploys from branches that are not the site’s main production branch.
  • dev: this context corresponds to local development environments run using Netlify Dev.

Besides these predefined contexts, sites can also use branch names as custom deploy contexts. For example, a branch called staging will match a deploy context called staging.

Deploy contexts allow you to override options from your site’s settings including the build command, the environment variables added to the build, Build Plugin configuration, and more.

Overrides are applied in a hierarchical order. The site’s global settings apply to each deploy, if we’re building the production site, and if you change options in your production context, they will be overridden. Only options that are set explicitly are overridden; if you leave one out, the build will use the value of the global settings or previous contexts. Environment variables are also overridden individually, for example, you can have access tokens as environment variables per context.

To configure deploy contexts, you must create a file called netlify.toml in the root of your Git repository. There, you can set as many contexts as you want to configure.

Note that, as the configuration file is stored in your repository, you should be mindful of what sensitive values you include. Where possible, we recommend you set sensitive values in the Netlify UI instead.

# Production context:
# All deploys from the main repository branch
# will inherit these settings. Be mindful
# when using this option and avoid committing
# sensitive values to public source repositories.
[context.production]
  command = "make production"
  [context.production.environment]
    ACCESS_TOKEN = "super secret"
  # Deploys from main branch run this plugin in the build.
  # Plugins context requires double brackets.
  [[context.production.plugins]]
    package = "@netlify/plugin-sitemap"

# Deploy Preview context:
# All deploys generated from a pull/merge request
# will inherit these settings. Be mindful
# when using this option and avoid committing
# sensitive values to public source repositories.
[context.deploy-preview.environment]
  ACCESS_TOKEN = "not so secret"

# Branch deploy context:
# All deploys that are not from a pull/merge request
# or from the production branch will inherit these settings.
[context.branch-deploy]
  command = "make staging"

# Dev context:
# Environment variables set here are available for local
# development environments run using Netlify Dev. These
# values can be overwritten on branches that have a more
# specific branch context configured.
[context.dev.environment]
  NODE_ENV = "development"

# Specific branch context:
# Deploys from this branch will take these settings
# and override their current ones.
[context.feature]
  command = "make feature"

[context."features/branch"]
  command = "gulp"

File-based configuration settings will override those set in the UI. In the netlify.toml file, settings for more specific contexts will override more general ones. For example, settings for a specific branch will override those for branch-deploy.

Visit our docs on file-based configuration to learn more about what you can do with deploy contexts.

# Deploy permissions

Netlify has a Deploy Request Policy that ensures that Netlify only builds and deploys changes pushed to private repositories from recognized authors. Recognized authors include Owners, Collaborators, and Git Contributors. Netlify also treats bots from GitHub Marketplace as recognized authors in private repositories.

Unrecognized authors, or non-team members, are people, automated services, or bots who are not associated with a Netlify team member account. This includes some Git-based services, like a CMS.

Similar to the Sensitive Variables policy, the Deploy Request Policy treats deploys from unrecognized authors as "untrusted."

# Working with deploy requests from non-team members

When a non-team member triggers a build, the subsequent deploy will have the status Pending approval on the Deploys page. The Deploy log will show a similar message of Deploy request is pending review. A pending deploy request can be approved by a team Owner, who must associate the non-team member with a Netlify team account before the build can start.

If the non-team member has an existing Netlify account, they can connect their Git provider account to their Netlify user.

Depending on your team plan, a team Owner can take the following actions for non-team members:

# Enable auto-approval for deploy requests

Team Owners can allow all builds for non-team members to run and deploy without needing approval or prompting a deploy request. This automatically adds the non-team member to the team as a Git Contributor.

Your team will be charged for auto-approved Git Contributors. See the Billing FAQ page for details.

To enable auto-approval for all deploy requests:

  1. Go to Team settings, then select Sites.

  2. Under Global Site settings, find the Auto-approve deploys from non-team members section and select Edit settings.

  3. Select Auto-approve, then Save.

# Match to an existing team member

To match an unrecognized author with an existing team member:

  1. Go to the Deploys page and find the pending deploy in the list of deploys.

  2. Select Further action required then select Match with existing team member.

  3. Use the list to select the existing team member to match.

  4. To confirm, select Match contributor and approve deploy.

# Add a non-team member as a Git Contributor

Not every Git committer in your repo must be added as a Git Contributor. Only the Git committer who you’d like to trigger a deploy needs to be added to your team as a Git Contributor.

To add a non-team member as a Git Contributor:

  1. Go to the Deploys page and find the pending deploy in the list of deploys.

  2. Select Further action required then select Approve and add as Git Contributor.

# Reject a pending deploy

To reject a non-team member’s pending deploy request, go to the Site overview page and select Reject next to the pending deploy. The pull/merge request or changes from a Git commit will not be deployed, even if it is merged, and any future deploys by the same contributor will continue to require approval.

# Sensitive variable policy

For sites connected to public repositories, Netlify may block some deploys depending on sensitive variable policy settings. A site member can approve or reject these deploys. Check out our sensitive variable policy docs for more information.

# More site deploys resources

Rollbacks