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.
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 Community forum topic about 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.
Branches and deploys
Netlify lets you control which branches in your Git repository you want to deploy.
- Production branch: the Git branch that Netlify uses to build and deploy changes to your site’s main URL (e.g.
- 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
stagingbranch example would deploy to
- 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-previewfollowed by the identifier number of the pull request or merge request. For example, a Deploy Preview for pull/merge request #42 will deploy to
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, go to Site settings > Build & deploy > Continuous Deployment > Deploy contexts, then click Edit settings. You can choose to deploy all branches (including future branches), or select individual branches you would like to deploy.
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, go to Site settings > Build & deploy > Continuous Deployment > Deploy contexts, then click Edit settings.
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
Deploy contexts allow you to override options from your site's settings including the build command, the environment variables added to the build, 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" # 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 (e.g. 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.
Did you find this doc useful?
Your feedback helps us improve our docs.