Continuous deployment works by connecting a GitHub 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 GitHub.
- No deploying without committing and pushing first
- Easy collaboration through pull requests
- Fix a typo through GitHub’s web UI from your mobile
- Let non-technical users contribute by using prose.io
Deploy contexts are the way to tell Netlify how to build your site. They give you flexibility to configure your site’s build depending 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 branch deployed that are not the main site’s production branch. This context only applies to our Pro, Open Source, and Global pricing tiers.
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 overriden 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 overriden. Only options that are set explicitly are overriden, if you leave one out, the build will use the value of the global settings, or previous contexts. Environment variables are also overriden 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. [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 to branches # that are not the main one 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"
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 checkout 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
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,
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
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 means subsequent builds will be 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,
hugo will build and deploy with the latest version of
hugo. You can specify a specific
hugo release like this:
0.16 are supported.
Netlify’s Pro plan 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
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.