Skip to content

Latest commit

 

History

History
87 lines (62 loc) · 2.92 KB

environment-variables.rst

File metadata and controls

87 lines (62 loc) · 2.92 KB

How to use custom environment variables

If extra environment variables are needed in the build process, you can define them from the project's :term:`dashboard`.

.. seealso::

   :doc:`/environment-variables`
     Learn more about how Read the Docs applies environment variables in your builds.

Go to your project's :menuselection:`Admin --> Environment Variables` and click on :guilabel:`Add Environment Variable`. You will then see the form for adding an environment variable:

Screenshot of the form for adding an environment variable

  1. Fill in the :guilabel:`Name` field, this is the name of your variable, for instance SECRET_TOKEN or PIP_EXTRA_INDEX_URL.

  2. Fill in the :guilabel:`Value` field with the environment variable's value, for instance a secret token or a build configuration.

  3. Check the :guilabel:`Public` option if you want to expose this environment variable to :doc:`builds from pull requests </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. In other words, do not use this option if your environment variable is a secret.

Note

Once you create an environment variable, you won't be able to edit or view its value in the :term:`dashboard`.

Finally, click on :guilabel:`Save`. Your custom environment variable is immediately active for all future builds and you are ready to start using it.

In the next sections, you can see a few examples of using environment variables. ⬇️

Accessing environment variables in code

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),
)

Accessing environment variables in build commands

You can also use any of these variables from :term:`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

Note

If you use ${SECRET_ENV} in a command in .readthedocs.yaml, the private value of the environment variable is not substituted in log entries of the command. It will also be logged as ${SECRET_ENV}.