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 just 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.

# 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, redirects, and Edge Handlers included in the deploy. It also indicates whether your site contains content served over insecure HTTP, known as mixed content.

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.

# 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. For example, www.yourcustomdomain.com and 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 the site as it would be if the proposed changes were merged. 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 branch deploys for other branches in your repository, select your site on the Sites page. Then go to Site settings > Build & deploy > Continuous Deployment > Deploy contexts, 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 branch deploys, Netlify will start watching those branches for new commits and pull/merge requests. As soon as you start pushing changes to those branches, you’ll see new deploys for those branches.

# Deploy Preview controls

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.

You can control in the UI whether or not Deploy Previews are generated for pull/merge requests. To change this, select your site and go to Site settings > Build & deploy > Continuous Deployment > Deploy contexts, 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 three 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.

Besides these three predefined contexts, sites can use also 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.

# Production context:
# All deploys from the main repository branch
# will inherit these settings.
[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.
[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"

# 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.

# More site deploys resources

Rollbacks