× press ESC to close

Netlify builds, deploys, and hosts your front end.

Continuous Deployment

Continuous deployment works by connecting a git repository to a Netlify site and keeping the two in sync.

It works for plain static sites, but it’s even more powerful when you’re using a static site generator or a front end build tool like Grunt, Gulp or Broccoli.

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

Deploy Contexts

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

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.  
# “base” is directory to change to before starting build, and
# “public” is the directory to publish (relative to root of your repo).
# “command” is your build command.

  base    = "site"
  publish = "public"
  command = "make"

# Production context: All deploys to the main
# repository branch will inherit these settings.
  command = "make production"
    ACCESS_TOKEN = "super secret"

# Deploy Preview context: All Deploy Previews
# will inherit these settings.
  ACCESS_TOKEN = "not so secret"

# Branch Deploy context: All deploys that are not in
# an active Deploy Preview will inherit these settings.
  command = "make staging"

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

  command = "gulp"

Build Environment variables

Netlify allows you to add build environment variables to your build so you can define the way your site is built. 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 production, deploy-preview or branch-deploy.

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, https://example.netlify.com or https://www.example.com.
  • DEPLOY_URL: This URL represents the unique URL for an individual deploy. It starts with a unique ID that identifies the deploy. For example, https://578ab634d6865d5cf960d620--open-api.netlify.com.
  • 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, https://deploy-preview-34--open-api.netlify.com or https://beta--open-api.netlify.com.

Set Node, Ruby, or Python version


You can choose the Ruby version we use to build your site. Our default Ruby version is 2.1.2 but you can specify a different version by adding a /.ruby-version file to your repository. We currently support the following Ruby versions:

  • 2.0.0-p247
  • 2.1.2
  • 2.2.1
  • 2.2.3
  • 2.3.0
  • 2.3.1
  • 2.3.3
  • 2.4.0
  • 2.4.1


You can set the Node.js version we use to build your site in two different ways:

  • Add a /.nvmrc to 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_VERSION environment 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 2.7.4, 3.4.0, 3.5.2, and 3.6.2 available. While 2.7.4 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

Dependency Cache

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:

Build Tool Directory Command
Jekyll _site jekyll build
Grunt dist grunt build
Middleman build middleman build
Roots public roots compile
Hugo public hugo
Gatsby public gatsby build
Build Tool
jekyll build
grunt build
middleman build
roots compile
gatsby build

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

Branch deploys

Netlify allows you to deploy individual Git branches to different subdomains. For example, take your domain example.com and put it on Netlify. Then, link your Git repository to your Netlify site. When you create a new branch and push it to the repository, Netlify will deploy the changes in the branch to new-branch.example.com.

Use Git’s regular branching strategy if your content will be merged in your main domain in the future. To create a regular branch you can use the following command:

git checkout -b new-branch

You can use Git’s orphan branches if you want to have completely different content in each subdomain. To create an orphan branch you can use the following command:

git checkout --orphan new-branch

You can safely remove any content from this new branch if you want, other branches won’t be affected. However, you won’t be able to merge and rebase this new branch with other branches either, so use this option only if you want to have different content that won’t ever be ported back to your main domain.

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.

Want to get started quick?