redmine-reporter/docs/CONFIG.md

Настройка redmine-reporter

Источники конфигурации

Приоритет, от высшего к низшему:

CLI-флаги  >  переменные окружения  >  .env  >  YAML  >  кодовые дефолты

Если значение не задано на верхнем уровне, берётся уровень ниже. .env и YAML работают одновременно — можно оставить оба, можно удалить .env после миграции.

YAML-конфиг

Основной файл: ~/.config/redmine-reporter/config.yml.

Создаётся с правами 0600 (владелец: чтение/запись, остальные: доступ запрещён). Директория ~/.config/redmine-reporter/ — с правами 0700.

Если права файла шире 0600, при запуске выводится предупреждение.

Структура

redmine:
  url: https://red.eltex.loc          # URL инстанса Redmine
  api_key: ${REDMINE_API_KEY}         # API-ключ (или plaintext)
  author: "Кокос А.А."               # Имя автора для отчёта
  verify_ssl: true                    # Проверка SSL-сертификата

period:
  precision: date                     # date | datetime
  default_from: "2026-06-01"          # Начало периода по умолчанию
  default_to: "2026-06-30"            # Конец периода по умолчанию
  dynamic: false                      # Автоматически сдвигать период

output:
  dir: ~/reports                      # Директория для отчётов
  filename: "{author}_{from}_{to}.{ext}"  # Шаблон имени файла
  default_format: xlsx                # Формат по умолчанию

email:
  smtp:
    host: smtp.example.com
    port: 587
    user: bot@example.com
    password: ${SMTP_PASSWORD}
    tls: true
  from: bot@example.com
  to:
    - boss@example.com
  subject: "Отчёт {author} за {period}"

Шаблон имени файла

Поле output.filename поддерживает подстановки:

Плейсхолдер	Описание	Пример
{author}	Имя автора (пробелы → _)	Кокос_А.А.
{from}	Начало периода, YYYY-MM-DD	2026-06-01
{to}	Конец периода, YYYY-MM-DD	2026-06-30
{date}	Конец периода, DD_MM_YYYY	30_06_2026
{ext}	Расширение файла без точки	xlsx

Неизвестные плейсхолдеры остаются в имени как есть.

Примеры шаблонов:

# По умолчанию
filename: "{author}_{from}_{to}.{ext}"    # → Кокос_А.А._2026-06-01_2026-06-30.xlsx

# Русский формат даты
filename: "отчёт_{date}.{ext}"            # → отчёт_30_06_2026.xlsx

# Без автора, только диапазон
filename: "report_{from}--{to}.{ext}"     # → report_2026-06-01--2026-06-30.xlsx

Подстановка переменных окружения

В любом строковом значении YAML можно использовать ${VAR} — при загрузке оно заменяется на значение переменной окружения:

redmine:
  api_key: ${REDMINE_API_KEY}

email:
  smtp:
    password: ${SMTP_PASSWORD}

Это безопаснее, чем хранить секреты plaintext в YAML. Однако plaintext-секреты не запрещены — если вписать api_key: "abc123" напрямую, система примет. Права 0600 — единственная защита.

Миграция с .env на YAML

Быстрый старт

# 1. Генерируем YAML из текущего .env
redmine-reporter --init-config

# 2. Проверяем, что создалось
cat ~/.config/redmine-reporter/config.yml

# 3. Редактируем под себя (шаблон имени, почту, etc.)
vim ~/.config/redmine-reporter/config.yml

Что делает --init-config

• Читает текущие значения из .env и переменных окружения.
• Формирует YAML со всеми секциями (redmine, period, output, email).
• Секреты (REDMINE_API_KEY, SMTP_PASSWORD) записывает как ${VAR}, если переменная существует, иначе — пустая строка.
• Создаёт файл с правами 0600, директорию — с 0700.

Флаги миграции

Флаг	Назначение
--init-config	Создать YAML и выйти
--init-config --force	Перезаписать существующий YAML
--config-path PATH	Сохранить YAML по указанному пути (по умолчанию ~/.config/redmine-reporter/config.yml)

Проверка после миграции

# Запустить без .env в текущей директории
cd /tmp
redmine-reporter --date 2026-06-01--2026-06-30

Если отработал — YAML-конфиг читается корректно. Если REDMINE_URL is required — проверь права:

ls -la ~/.config/redmine-reporter/
# config.yml должно быть -rw------- (600)
# директория должна быть drwx------ (700)

Сосуществование .env и YAML

Можно оставить оба источника. .env имеет более высокий приоритет, чем YAML:

.env значения переопределяют YAML, если заданы
YAML работает как базовый слой для всего, что не в .env

Это safe — если с YAML что-то пойдёт не так, просто положи .env обратно.

Откат

# Удалить YAML-конфиг — система вернётся на .env
rm ~/.config/redmine-reporter/config.yml

.env (legacy)

Для обратной совместимости .env продолжает работать без изменений.

REDMINE_URL=https://red.eltex.loc
REDMINE_API_KEY=your-api-key
REDMINE_AUTHOR=Кокос А.А.
DEFAULT_FROM_DATE=2026-06-01
DEFAULT_TO_DATE=2026-06-30

Если ни .env, ни YAML не заданы — используются кодовые дефолты (текущий месяц как период, стандартный путь сертификатов, пустой автор).

Безопасность

• YAML-конфиг: права 0600, директория 0700.
• Права шире 0600 → warning в stderr при каждом запуске.
• Секреты рекомендуется хранить через ${VAR}, а не plaintext.
• .env не рекомендуется для постоянных настроек — оставьте его только для CI/CD или временных переопределений.