Environment Variables - Using Secrets in Update-Watcher Config

Update-Watcher supports environment variable substitution in its YAML configuration file. This allows you to keep secrets like API tokens, webhook URLs, and passwords out of the config file itself, which is a best practice for security, CI/CD pipelines, and shared environments.

Substitution Syntax

Examples in Config

notifiers:
  - type: slack
    enabled: true
    options:
      webhook_url: "${SLACK_WEBHOOK_URL}"

  - type: telegram
    enabled: true
    options:
      bot_token: "${TELEGRAM_BOT_TOKEN}"
      chat_id: "${TELEGRAM_CHAT_ID}"

  - type: email
    enabled: true
    options:
      smtp_host: "${SMTP_HOST:-smtp.gmail.com}"
      smtp_port: 587
      username: "${SMTP_USERNAME}"
      password: "${SMTP_PASSWORD}"
      from: "${SMTP_FROM:-alerts@example.com}"
      to: ["admin@example.com"]

The UPDATE_WATCHER_ Prefix

Update-Watcher uses Viper for configuration management. Viper automatically maps environment variables with the UPDATE_WATCHER_ prefix to config file keys.

The mapping follows this pattern:

• Nested keys are separated by underscores.
• All characters are uppercase.

These prefixed environment variables override values from the config file, following the standard configuration precedence:

1. CLI flags (highest priority)
2. UPDATE_WATCHER_ environment variables
3. Config file values (lowest priority)

Note that the UPDATE_WATCHER_ prefix mechanism is separate from the ${VAR} substitution syntax. The prefix approach overrides config keys directly through Viper, while ${VAR} performs string replacement within the YAML file itself. Both can be used together.

Using a .env File

For local development or servers where you want to keep secrets in a separate file, you can use a .env file. This file contains one environment variable per line in KEY=VALUE format.

Create a .env file (for example, at /etc/update-watcher/.env on a server or next to the binary during development):

# /etc/update-watcher/.env
# Notification service credentials
SLACK_WEBHOOK_URL=<your-slack-webhook-url>
TELEGRAM_BOT_TOKEN=<your-telegram-bot-token>
TELEGRAM_CHAT_ID=<your-telegram-chat-id>
SMTP_PASSWORD=<your-smtp-password>

# Pushover
PUSHOVER_APP_TOKEN=<your-pushover-app-token>
PUSHOVER_USER_KEY=<your-pushover-user-key>

Load the .env file before running Update-Watcher:

export $(grep -v '^#' /etc/update-watcher/.env | xargs) && update-watcher run

.env File in Cron

When running via cron, environment variables from your shell profile are not automatically available. To load a .env file in a cron job, include the export command in the cron entry:

0 7 * * * export $(grep -v '^\#' /etc/update-watcher/.env | xargs) && /usr/local/bin/update-watcher run --quiet

Alternatively, define the variables directly in the crontab:

SLACK_WEBHOOK_URL=<your-slack-webhook-url>
0 7 * * * /usr/local/bin/update-watcher run --quiet

.env File Permissions

Set strict permissions:

chmod 600 /etc/update-watcher/.env
chown update-watcher:update-watcher /etc/update-watcher/.env

Make sure the .env file is listed in .gitignore if it exists inside a repository.

Common Environment Variables

The following table lists environment variables commonly referenced in Update-Watcher configurations. These are not built-in to Update-Watcher; they are standard names used in the ${VAR} substitution pattern in your config file.

Best Practices

Next Steps

• Security Best Practices – File permissions, dedicated users, and network security.
• Config File Reference – Full YAML configuration reference.
• First Run – Setting up your first configuration.