Gatsby Cloud Docs

Managing Environment Variables

Managing environment variables in Gatsby Cloud

Table of Contents

An environment variable references a value that can affect how running processes will behave on a computer, for example in staging and production environments. In Gatsby Cloud, the most important environment variables are the ones that will authorize your instance to pull content from your content management system (CMS).

This doc will address managing environment variables in general in Gatsby Cloud. For specific instructions on setting up environment variables to work with your CMS, see the CMS-specific setup instructions.

There are primarily three different situations you will encounter concerning environment variables:

  1. Creating a new Gatsby Cloud site using autoprovisioning.
  2. Adding an existing site to Gatsby Cloud using GitHub.
  3. Managing environment variables for an existing site on Gatsby Cloud.

You have the option of setting specific environment variables for both Preview and Builds. For environment variables that affect preview you’ll want to use “Preview Environment Variables” and for builds, “Builds Environment Variables”. Think of this as staging versus production. If your environment variables facilitate a connection to a CMS it’s likely you’ll want to see draft content in your Preview instance and not your built live site.

Managing environment variables when autoprovisioning a new site

When you autoprovision a new Gatsby Cloud site using one of the preconfigured starters, Gatsby Cloud will handle setting up the environment variables for the CMS. You won’t see any options for environment variables until the site is created. Then you’ll be able to manage the environment variables in your site settings.

Managing environment variables when adding a new site

When adding an existing site to Gatsby Cloud, you’ll have the opportunity to add whatever environment variables you need in Step 3: Setup.

You can add environment variables one by one. If you have many variables, that can get tedious. You can also bulk add environment variables by copy-pasting from wherever your variables are stored, and adding via the “Bulk Add Variables” button.

When adding environment variables in bulk, the input should be formatted as key/value pairs separated by an = sign. Each pair should also be separated by a hard return. For example:

Managing environment variables in an existing site

To manage environment variables on an existing Gatsby Cloud site:

  1. Navigate to the site details page of the site you want to manage.
  2. Click the “Site Settings” tab.
  3. In the “General” section of “Site Settings” you’ll find the sections for configuring environment variables.

Delete unneeded variables or add new ones — one by one, or in bulk.

Specific environment variables

Environment variable key names can be anything, as long as they match the process.env.{KEY_NAME} used in your gatsby-config.js file.

However, the keys below are explicitly supported by Gatsby Cloud without the need for additional configuration.

Gatsby Cloud configuration

These variables allow you to configure features of Gatsby Cloud.

  • NODE_VERSION: Specify the version of Node.js your project should use. For example, NODE_VERSION=10. Defaults to 12.
  • NPM_TOKEN: Use to access private npm modules.
  • NPM_REGISTRY: Use to set the url of a private registry.
  • YARN_FLAGS: Flags that are passed through to the yarn command.
  • NODE_OPTIONS: Passed through as options for Node.js. For example, NODE_OPTIONS=--max_old_space_size=4096.
  • PREFIX_PATHS: Set to true if you normally use the --prefix-paths flag during gatsby-build. See the docs on prefix-paths.

Read-only variables

These variables are pre-defined for both Builds and Preview environments. They are set automatically and cannot be changed. You can reference them in your gatsby-config.js or anywhere else you would normally reference an environment variable.

  • BRANCH: The name of the current git branch. Useful for swapping environment variables depending on the branch.
  • CI: Always true.
  • GATSBY_CLOUD: Always true. Useful for checking if your build is running on Gatsby Cloud.
© 2020 Gatsby, Inc.