Build environment variables

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 Community forum for guidance on how to access environment variables during your site build.

Declare variables

You can create your own environment variables via the following channels:

  • 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 runtime, snippet injection during post processing, and more.

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 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 list entry for an untrusted deploy request, including the Deploy Preview number, Git author username, link to review changes, and buttons to accept or reject

  • 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-preview context 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.

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

  • NETLIFY: Always true. Can be used to check if the build is running on Netlify.
  • BUILD_ID: Unique ID for the build; for example: 5d4aeac2ccabf517d2f219b8.
  • CONTEXT: Name of the build's deploy context. It can be production, deploy-preview or branch-deploy.
  • _system_arch: The system architecture of the current build image; for example, x86_64.
  • _system_version: The version of Ubuntu Linux running in the current build image; for example, 16.04.

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 (false).
  • REVIEW_ID: If from a pull/merge request, the ID of the request and the Deploy Preview it generated (e.g. 1211). These two numbers will always match. (For example, deploy-preview-12 is 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, https://petsof.netlify.app or https://www.petsofnetlify.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://5b243e66dd6a547b4fee73ae--petsof.netlify.app.
  • 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://feature-branch--petsof.netlify.app or https://deploy-preview-1--petsof.netlify.app.
  • DEPLOY_ID: Unique ID for the deploy; for example, 578ab634d6865d5cf960d620. Matches the beginning of DEPLOY_URL.
  • SITE_NAME: Name of the site, its Netlify subdomain; for example, petsof.
  • SITE_ID: Unique ID for the site; for example, 1d01c0c0-4554-4747-93b8-34ce3448ab95.
  • NETLIFY_IMAGES_CDN_DOMAIN: If image compression post processing is enabled, the base URL used for all processed images; for example, d33wubrfki0l68.cloudfront.net.

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.