Understanding environment variables

Read the Docs allows you to define your own environment variables to be used in the build process. It also defines a set of default environment variables with information about your build. These are useful for different purposes:

Custom environment variables are useful for adding build secrets such as API tokens.
Default environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs.

Custom environment variables are defined in the dashboard interface in Admin ‣ Environment variables. Environment variables are defined for a project’s entire build process, with 2 important exceptions.

Aside from storing secrets, there are other patterns that take advantage of environment variables, like reusing the same monorepo configuration in multiple documentation projects. In cases where the environment variable isn’t a secret, like a build tool flag, you should also be aware of the alternatives to environment variables.

Environment variables and build process

When a build process is started, pre-defined environment variables and custom environment variables are added at each step of the build process. The two sets of environment variables are merged together during the build process and are exposed to all of the executed commands, with pre-defined variables taking precedence over custom environment variables.

There are two noteworthy exceptions for custom environment variables:

Build checkout step: Custom environment variables are not available during the checkout step of the build process
Pull Request builds: Custom environment variables that are not marked as Public will not be available in pull request builds

Patterns of using environment variables

Aside from storing secrets, environment variables are also useful if you need to make either your .readthedocs.yaml or the commands called in the build process behave depending on pre-defined environment variables or your own custom environment variables.

Example: Multiple projects from the same Git repo

If you have the need to build multiple documentation websites from the same Git repository, you can use an environment variable to configure the behavior of your build commands or Sphinx conf.py file.

An example of this is found in the documentation project that you are looking at now. Using the Sphinx extension sphinx-multiproject, the following configuration code decides whether to build the user or developer documentation. This is defined by the PROJECT environment variable:

Read the Docs’ conf.py [1] is used to build 2 documentation projects.

from multiproject.utils import get_project

# (...)

multiproject_projects = {
    "user": {
        "use_config_file": False,
        "config": {
            "project": "Read the Docs user documentation",
        },
    },
    "dev": {
        "use_config_file": False,
        "config": {
            "project": "Read the Docs developer documentation",
        },
    },
}


docset = get_project(multiproject_projects)

Alternatives to environment variables

In some scenarios, it’s more feasible to define your build’s environment variables using the .readthedocs.yaml configuration file. Using the dashboard for administering environment variables may not be the right fit if you already know that you want to manage environment variables as code.

Consider the following scenario:

The environment variable is not a secret.

and
The environment variable is used just once for a custom command.

In this case, you can define the environment variable as code using Build process customization. The following example shows how a non-secret single-purpose environment variable can also be used.

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.12"
  jobs:
    post_build:
      - EXAMPLE_ENVIRONMENT_VARIABLE=foobar command --flag