Continuous deployment works by connecting a git repository to a Netlify site and keeping the two in sync.
Netlify will run your build command and deploy the result whenever you push to your git repo.
- No deploying without committing and pushing first
- Easy collaboration through pull requests
- Fix a typo through your git provider’s web UI from your mobile
- Edit content without code by using a static site CMS, Netlify CMS
Branches & Deploys
- Production branch: the Git branch that Netlify uses to build and deploy changes to your site’s main URL, for example
- 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.com. If you use Netlify DNS, you can enable branch subdomains, so the
stagingbranch example would deploy to
- Deploy Preview: 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, pull request #42 will automatically trigger a Deploy Preview at
Branch Deploy controls
Netlify lets you control which branches in your Git repository you want to deploy. By default, Netlify deploys the site’s production branch after every change, and builds deploy previews for all pull/merge requests on that branch.
To generate branch deploys for other branches in your repository, go to Settings > Build & deploy > Continuous Deployment > Deploy settings, 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 branch deploys and deploy previews.
Deploy contexts are a way to tell Netlify how to build your site. They give you the flexibility to configure your site’s build 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 Requests and Merge Requests integrations.
- 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
Currently, deploy contexts allow you to override four options from your site’s settings. The build command, the base directory where your site is built from, the publish directory where the build puts the processed files, and the environment variables added to the build. All these options are overridden in a hierarchical order. The site’s global settings apply to each deploy, if we’re building the production site, and 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 base of your Git repository. There, you can set as many contexts as you want to configure.
# Global settings applied to the whole site. # # “publish” is the directory to publish (relative to root of your repo), # “command” is your build command, # “base” is directory to change to before starting build. if you set base: # that is where we will look for package.json/.nvmrc/etc not repo root! [build] base = "site" publish = "public" command = "make" # Production context: All deploys to the main # repository branch will inherit these settings. [context.production] command = "make production" [context.production.environment] ACCESS_TOKEN = "super secret" # Deploy Preview context: All Deploy Previews # will inherit these settings. [context.deploy-preview.environment] ACCESS_TOKEN = "not so secret" # Branch Deploy context: All deploys that are not in # an active Deploy Preview 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"
These 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 branch will override a those for a branch-deploy).
We’ve also published this more thorough and complete netlify.toml example and description.
Build Environment variables
Netlify build environment variables are accessible during your build, allowing you to change behaviors based on deploy parameters, or to include information you don’t want to save in your repository, like API keys. You can create your own build environment variables in the
netlify.toml file, or in your site dashboard under Settings > Build & deploy > Continuous Deployment > Build environment variables. Variable values in the
netlify.toml file will override values set in the UI.
In addition to the variables you choose to define, Netlify has a number of pre-defined variables built in. Those variables are:
- REPOSITORY_URL: URL to the Git repository the build pulls changes from.
- BRANCH: Reference to check out after fetching changes from the Git repository.
- PULL_REQUEST: Whether the build is from a pull request or not.
- HEAD: Name of the head branch received from a Git provider.
- COMMIT_REF: Reference of the commit we’re building.
- CONTEXT: Name of the context a deploy is built around, it can be
- REVIEW_ID: the ID of the pull request and deploy preview (e.g.
1211). These two numbers will always match (
deploy-preview-12is for PR # 12 in your repository)
If your build is triggered from one of your inbound webhooks, Netlify also has three webhook-specific variables:
- WEBHOOK_TITLE: Title of the incoming webhook.
- WEBHOOK_URL: URL of the incoming webhook.
- WEBHOOK_BODY: Body of the request sent to the incoming webhook.
Each build environment includes three URLs that you can use at your convenience. This section describes each one of them:
- URL: This URL represents the main address to your site. It can be either a netlify subdomain or your own custom domain if you set one. For example,
- DEPLOY_URL: This URL represents the unique URL for an individual deploy. It starts with a unique ID that identifies the deploy. For example,
- DEPLOY_PRIME_URL: This URL represents the primary URL for an individual deploy, or a group of them, like branch deploys and deploy previews. For example,
Set Node, Ruby, or Python version
You can choose the Ruby version we use to build your site. Our default Ruby version is
2.3.6 but you can specify a different version by adding a
/.ruby-version file to your repository. We support any released version of Ruby that rvm understands. For fastest builds use one of these versions which are installed automatically in the build environment:
Our default for new sites is Node 8 LTS latest, but you can choose the Node.js version we use to build your site in two different ways:
- Add a
/.nvmrcto your repository. This will also tell any other developer using the repository which version of Node.js it depends on. You can either set a specific version or just have a major version in the file, like the number 6 for the latest version of node 6.x
- Set a
NODE_VERSIONenvironment variable. You can set this as a variable in the build environment either while linking the repository or afterward from the site settings screen in our UI. The value inside can be anything you would use with nvm.
We have Python versions
3.6 available. While
2.7 is the default, you can select one of those versions with a
runtime.txt containing the version number (from those 4) that you prefer.
Netlify will install any dependencies from any Gemfile, package.json, bower.json or requirements.txt in the root of your repository, before running your build. Any executables from these dependencies will be made available from the PATH.
Make sure to include your build tool in these dependencies:
- If you’re using Jekyll, make sure to add a Gemfile that requires the jekyll gem
- If you’re using Grunt, make sure to add a package.json with grunt-cli as a dependency
- If you’re using Roots, make sure to install roots in your local package.json and not just globally
- If you’re using mkdocs, make sure to add a requirements.txt with mkdocs>=0.9.0
- If you’re using gatsby, make sure to add gatsby-cli to your local package.json and not just globally
The first build you do can take some time while we install all of your dependencies. After the initial build, we’ll cache the dependencies so we don’t have to start from scratch each time you push an update. This is intended to make subsequent builds really fast.
Common configuration directives
Here are some examples of configuring your site for common build tools:
For Jekyll hosting, make sure you have a Gemfile and a Gemfile.lock checked into your repository, specifying the Jekyll version you want to use.
For Roots hosting, make sure you add
roots to your package.json.
For Hugo hosting, the build command
hugo will build and deploy with the version 0.17 of Hugo. For versions 0.13, 0.14, 0.15, 0.16, 0.17, 0.18 and 0.19, you can specify a specific Hugo release like this:
hugo_0.15. For version
0.20 and above, use the regular
hugo command and create a Build Environment Variable called
HUGO_VERSION and set it to the version of your choice. (More details can be found on our blog.)
Notice something is incorrect or outdated?
First off, great eye! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.