Netlify environment variables are accessible during your build. This allows you to change behaviors based on deploy parameters or to include information you don’t want to save in your repository, such as API keys.
This page describes specific variables available in the Netlify build environment, as well as how to set your own. Visit our Forums for a verified Support Guide on how to access environment variables during your site build.
# Declare variables
You can create your own environment variables in the following ways:
- In the Netlify configuration file. File-based configuration allows you to set different environment variables for different deploy contexts. Variable values set in the configuration file will override values set in the UI.
- In Site settings > Build & deploy > Environment > Environment variables. Variable values set under site settings will override the team-level settings.
- In Team settings > Sites > Global site settings > Shared environment variables. Variables set at the team level are shared by all sites owned by the team. These can be overridden by settings at the site level. (This feature may not be available on all plans.)
Environment variables set in the UI are also accessible in other environments associated with your site, including serverless functions at execution time, snippet injection during post processing, and more.
Deploy to apply changes
Environment variable changes are applied at deploy time and require a re-deploy to take effect.
# Sensitive variable policy
Some environment variables you may want to keep private. This can pose a challenge for sites connected to public repositories, where anyone can trigger a Deploy Preview by making a pull/merge request from a fork. We call these deploys untrusted deploys.
Site members’ deploys are trusted
Git provider accounts connected to a site member can trigger deploys without restrictions, even from forks. If a site member’s deploys are being treated as untrusted, make sure they connect their Git provider account to their Netlify user.
Netlify allows you to control whether untrusted deploys can access sensitive environment variables by choosing a sensitive variable policy. The policy is only available for sites connected to public repositories, and it includes the following options:
Require approval (default): All untrusted deploys must be approved by a site member before the build can start. Deploys awaiting approval can be found at the top of the deploy list on the site Deploys tab. Accepting or rejecting a deploy request does not affect the status of the originating pull/merge request.
Deploy without sensitive variables: Untrusted deploys will build automatically, but variables identified as sensitive will not be passed to the deploy environment. You can adjust your site code to accommodate builds without sensitive variables present, or you can assign “public” versions of your variables under the
deploy-previewcontext in your Netlify configuration file.
Deploy without restrictions: Treats untrusted deploys like any other Deploy Preview, building automatically with all variables present. Use this option only if you are not concerned about the potential exposure of any of your site’s environment variables.
By default, when Netlify detects potentially sensitive environment variables in your site settings, we automatically apply the default setting above, requiring approval for all untrusted deploys. You can change this policy at any time in Site settings > Build & deploy > Environment > Sensitive variable policy.
Self-hosted repositories are considered private
Because self-hosted GitHub/GitLab instances enable a higher degree of access control, we treat all self-hosted repositories as private. This means you won’t be able to set a sensitive variable policy for a site linked to a repo on GitHub Enterprise Server or GitLab self-managed.
# Deploy request notifications
When your sensitive variable policy is set to require approval for all untrusted deploys, you can add deploy notifications to trigger when a deploy request is pending, approved, or rejected. Visit the deploy notifications doc to learn more about the types of notifications available and how to configure them.
# Netlify configuration variables
By setting custom values for certain reserved environment variables, you can change some aspects of your build, such as language and dependency versions. Links in the variable descriptions below provide more information about requirements, defaults, and accepted values.
NODE_VERSION: Sets the Node.js version.
NODE_ENV: Sets the Node.js environment.
NPM_VERSION: Sets the npm version.
NPM_FLAGS: Passed as flags on the
NPM_TOKEN: Used for fetching private npm modules.
NETLIFY_USE_YARN: Overrides the default behavior for installing and running Yarn.
YARN_VERSION: Sets the Yarn version.
YARN_FLAGS: Passed as flags on the
RUBY_VERSION: Sets the Ruby version.
PHP_VERSION: Sets the PHP version. Default and available values are determined by the site build-image.
PYTHON_VERSION: Sets the Python version.
HUGO_VERSION: Sets the Hugo version.
SWIFT_VERSION: Sets the Swift version.
GO_VERSION: Sets the Go version. Default and available values are determined by the site build-image.
GO_IMPORT_PATH: Specifies the Go import path for your build and functions.
AWS_LAMBDA_JS_RUNTIME: Sets the Node.js runtime version for Netlify Functions.
CI: Defaults to
true, indicating that the build is running in a Continuous Integration (CI) environment. If this causes issues for your build, you can override the variable by adding
CI=''to the beginning of your site build command.
The following variables should be set in the Netlify UI rather than in
netlify.toml. This is because the Netlify configuration file is read after your repository has been cloned.
GIT_LFS_ENABLED: Undefined by default. If set, we’ll use
git lfs cloneto check out your repository — otherwise we use
GIT_LFS_ENABLEDis set, this specifies by file extension which Git LFS files will be downloaded when cloning your repository. Any other file extensions will have only text pointer files downloaded instead of the original media files. The default file extensions are determined by the site build-image.
NETLIFY_BUILD_DEBUG: Set this to
trueto print additional debugging information in the build logs. The output does not contain sensitive information. To disable debugging, delete the variable. Alternatively, delete everything in the variable’s Value field.
# Read-only variables
In addition to the variables you choose to declare, Netlify has a number of pre-defined variables built in. The following variables are automatically set for your builds, and their values are not changeable.
# Build metadata
true. Can be used to check if the build is running on Netlify.
BUILD_ID: Unique ID for the build; for example:
CONTEXT: Name of the build’s deploy context. It can be
_system_arch: The system architecture of the current build image; for example,
_system_version: The version of Ubuntu Linux running in the current build image; for example,
# Git metadata
REPOSITORY_URL: URL for the linked Git repository.
BRANCH: Reference to check out after fetching changes from the Git repository. Can be useful for split testing.
HEAD: Name of the head branch received from a Git provider.
COMMIT_REF: Reference ID (also known as “SHA” or “hash”) of the commit we’re building.
CACHED_COMMIT_REF: Reference ID (also known as “SHA” or “hash”) of the last commit that we built before the current build.
PULL_REQUEST: Whether the build is from a pull/merge request (
true) or not (
REVIEW_ID: If from a pull/merge request, the ID of the request and the Deploy Preview it generated (for example,
1211). These two numbers will always match. (For example,
deploy-preview-12is for PR #12 in your repository.)
# Deploy URLs and metadata
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,
DEPLOY_ID: Unique ID for the deploy; for example,
578ab634d6865d5cf960d620. Matches the beginning of
SITE_NAME: Name of the site, its Netlify subdomain; for example,
SITE_ID: Unique ID for the site; for example,
NETLIFY_IMAGES_CDN_DOMAIN: If image compression post processing is enabled, the base URL used for all processed images; for example,
# Build hook metadata and payload
If your build is triggered from a custom build hook, Netlify also has three build-hook-specific variables:
INCOMING_HOOK_TITLE: Title of the build hook.
INCOMING_HOOK_URL: URL of the build hook.
INCOMING_HOOK_BODY: The payload of the request sent to the build hook URL.
Did you find this doc useful?
Your feedback helps us improve our docs.