Environment Variables¶
Read the Docs supports two types of environment variables in project builds:
Both are merged together during the build process and are exposed to all of the executed commands. There are two exceptions for user-defined environment variables however:
User-defined variables are not available during the checkout step of the build process
User-defined variables that are not marked as public will not be available in pull request builds
Default environment variables¶
Read the Docs builders set the following environment variables automatically for each documentation build:
- READTHEDOCS¶
Whether the build is running inside Read the Docs.
- Default
True
- READTHEDOCS_VERSION¶
The slug of the version being built, such as
latest
,stable
, or a branch name likefeature-1234
. For pull request builds, the value will be the pull request number.
- READTHEDOCS_VERSION_NAME¶
The verbose name of the version being built, such as
latest
,stable
, or a branch name likefeature/1234
.
- READTHEDOCS_VERSION_TYPE¶
The type of the version being built.
- Values
branch
,tag
,external
(for pull request builds), orunknown
- READTHEDOCS_LANGUAGE¶
The locale name, or the identifier for the locale, for the project being built. This value comes from the project’s configured language.
- Examples
en
,it
,de_AT
,es
,pt_BR
User-defined environment variables¶
If extra environment variables are needed in the build process (like an API token), you can define them from the project’s settings page:
Go to your project’s Admin > Environment Variables
Click on Add Environment Variable
Fill the
Name
andValue
Check the Public option if you want to expose this environment variable to builds from pull requests.
Warning
If you mark this option, any user that can create a pull request on your repository will be able to see the value of this environment variable.
Click on Save
Note
Once you create an environment variable, you won’t be able to see its value anymore.
After adding an environment variable, you can read it from your build process, for example in your Sphinx’s configuration file:
import os
import requests
# Access to our custom environment variables
username = os.environ.get("USERNAME")
password = os.environ.get("PASSWORD")
# Request a username/password protected URL
response = requests.get(
"https://httpbin.org/basic-auth/username/password",
auth=(username, password),
)
You can also use any of these variables from user-defined build jobs in your project’s configuration file:
version: 2
build:
os: ubuntu-22.04
tools:
python: 3.10
jobs:
post_install:
- curl -u ${USERNAME}:${PASSWORD} https://httpbin.org/basic-auth/username/password