Secrets, passwords and access tokens

Secrets, passwords and access tokens#

You may require access to secrets, passwords and access tokens for your documentation in a local development environment, or while deploying documentation using GitHub actions or Read the Docs. This section documents the recommended workflows for each of these cases.

Access a secret locally in a .env file#

Access your secret as an environment variable in a local development environment by storing it in a .env file. A .env file is a popular language-agnostic solution for secrets management and is parsed with the python-dotenv package.

Caution

Keep your secret secure and do not upload the .env file to a Git repo. Add .env to your .gitignore list.

  1. Create a new .env file in the root folder of your project.

  2. Edit the .env file to include

    SECRET_NAME=<enter your secret here>

  3. Save and close.

Access your secret in a Python code with

pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()
SECRET_NAME = os.environ["SECRET_NAME"]

Access organization-level secrets in GitHub actions#

Add your secret as a GitHub an organizational-level repository secret to be used in GitHub actions when you build and publish online.

Note

To create a secret for the 2i2c organization for multiple users, see the GitHub Docs – Using secrets in GitHub actions. We recommend organization-level secrets against individual-level secrets to minimize the need to create duplicate secrets for multiple repositories.

  1. Navigate to the 2i2c GitHub organization.

  2. In the Settings menu, click on Secrets and Tokens > Actions in the left-side menu.

  3. Under the Organization Secrets section, click on the New organization secret button.

  4. Enter the name of your secret in the Name field and paste in the value of your secret in the Secret field.

  5. Scope the secret to the relevant select repositories under the Repository access dropdown.

  6. Click Add secret to confirm.

Following this, adjust your GitHub action workflow file to make the secret available to your job with the env key value. See the GitHub Docs – Using secrets in GitHub actions or the example code snippet from the team-compass/.github/workflows/test-docs.yaml file below:

jobs:
  test-docs:
    steps:
      - name: make dirhtml
        env:
          SECRET_NAME: ${{ secrets.SECRET_NAME }}
        run: |
          make my_project

Caution

Repository secrets are not passed to workflows that are triggered by a pull request from a forked repository.

Access the secret on Read the Docs#

2i2c deploys documentation using Read the Docs. Ensure that the secret is available as an environment variable in the Read the Docs build environment:

  1. Navigate to https://readthedocs.org and log into your account.

  2. Click on the name of the project you wish to enable the secret for, e.g. 2i2c Team Compass.

  3. Click the Admin button.

  4. Click the Environment Variables section in the left sidebar and then click on Add Environment Variable.

  5. Enter the secret name into the Name field and paste in your secret value into the Value field.

  6. Important: leave the box Expose this environment variable in PR builds? unchecked to keep your token secret.

  7. Confirm by clicking Save.

Caution

Custom environment variables not marked as public are not available in pull request builds. See the readthedocs docs – Environment variables and build process.

Contents