Почему секрета нет в git
На пути «Свой сервер» /opt — git-репозиторий, но секретов в нём нет: их не пускает белый список .gitignore
(«Конфиги серверов в git»). Секреты лежат только на сервере — в /srv/secrets/<каталог>/ и в .env стеков
(«Секреты в Docker-стеках»). Отсюда три неудобства:
- поменять секрет можно только на сервере, по SSH. С «Деплой без SSH» всё остальное подтягивается через git, а секрет — нет;
- истории нет: через месяц не узнать, какой адрес пинга стоял до правки;
- на второй сервер секреты переносим руками, на новый — из бэкапа («Переезд на новый сервер»).
Открытым секрет в git не кладём даже в приватный репозиторий: история хранит значение навсегда, а копия есть у GitHub
и в каждом клоне («Секрет в коммите»). Зашифрованный — кладём. sops шифрует значения внутри файла и оставляет
открытыми имена, а расшифровывает их ключ age. Ключей два: один на компьютере, другой у сервера, и каждый открывает
все файлы в secrets/.
компьютер git (GitHub, infra-web1) web1
ключ age владельца /opt/secrets/ — зашифровано ключ age сервера
sops edit ─── git push ───▶ .sops.yaml — открытые ключи ───▶ git pull, secrets.sh
/srv/secrets/<каталог>/ 400
/opt/<стек>/.env 600
/opt/secrets/ повторяет /srv/secrets/ один в один: secrets/deploy/hc-url сервер выкладывает в
/srv/secrets/deploy/hc-url. .env стека лежит в secrets/<стек>/.env и выкладывается в /opt/<стек>/.env.
Что видно в зашифрованном файле
secrets/gatus/.env до шифрования — одна строка NTFY_TOPIC=lab-only-topic-1. После sops encrypt -i:
NTFY_TOPIC=ENC[AES256_GCM,data:Ry7UoYwtqg0uGhMbo2WeTQ==,iv:tTBrTjytrlN6ArREFnUiUNZXZ2EuA4dmg/qiFrLVUjA=,tag:…,type:str]
sops_age__list_0__map_enc=-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA0MEs5…
sops_age__list_0__map_recipient=age1zqfsfym3g0frgrmxkq9fzg34kw0w6x6x9rrf6mfhp8jz92m4t94smvzch4
sops_age__list_1__map_enc=-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB4Zk8y…
sops_age__list_1__map_recipient=age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvg
sops_lastmodified=2026-11-12T15:05:08Z
sops_mac=ENC[AES256_GCM,data:l/lUE+MvplSzPjwFIprKgH7mOvf3zWzUxo/yedzrR0nyTc0l6P24xDCzfObUlBmv3aNGXsuy/PkfjeAJD…,type:str]
sops_unencrypted_suffix=_unencrypted
sops_version=3.13.3
Значения зашифрованы одним ключом данных, а сам он лежит в файле несколько раз — по копии для каждого получателя.
Пара list_N — это открытый ключ age (recipient) и ключ данных, зашифрованный для него (enc).
Всем, у кого есть репозиторий, видно:
- имена переменных и их число — поэтому в имя секрет не кладём;
- длину значения: у 16 символов
lab-only-topic-1вdata:16 байт, 24 знака base64; - для кого зашифрован файл (
recipient) и когда его правили (lastmodified).
Зашифрованы значения и комментарии. Файл без расширения — token, hc-url — sops хранит как JSON с одним
значением data, и зашифровано всё содержимое.
Правка одного значения меняет в diff три строки: само значение, sops_lastmodified и sops_mac. По git log -p
видно, какая переменная менялась и когда, но не видно, на что.
Настройка
Почти всё делаем на сервере. Открытые значения уже лежат там — там их и шифруем, и на компьютер они не попадают.
Хук и secrets.sh тоже создаём на сервере и коммитим оттуда, как deploy.sh в «Деплой без SSH»: так git
запомнит, что файлы исполняемые. Файл, добавленный в git на Windows, получает режим 100644. На сервере secrets.sh
с таким режимом не запустится, а хук git пропустит — hint: The '.githooks/pre-commit' hook was ignored because it's not set as executable — и закоммитит без проверки.
sops и age на сервере
В apt Ubuntu 24.04 пакета sops нет — берём бинарник с GitHub со сверкой суммы. age из apt нужен только ради
age-keygen: сам sops его не вызывает.v=3.13.3 curl -fLO https://github.com/getsops/sops/releases/download/v$v/sops-v$v.linux.amd64 curl -fLO https://github.com/getsops/sops/releases/download/v$v/sops-v$v.checksums.txt sha256sum -c --ignore-missing sops-v$v.checksums.txt # sops-v3.13.3.linux.amd64: OK sudo install -m 755 sops-v$v.linux.amd64 /usr/local/bin/sops sudo apt install age sops --version --disable-version-check # sops 3.13.3Ключ сервера
Ключ кладём туда, где sops ищет его сам:
sudo install -d -m 700 /root/.config/sops/age sudo age-keygen -o /root/.config/sops/age/keys.txt # Public key: age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvgage-keygenставит файлу права 600 и существующий ключ не перезаписывает.sudoзадаётHOME=/root, поэтомуsudo sopsнаходит ключ без переменных. Открытый ключ — строкаPublic key:— понадобится в.sops.yaml.sops, age и свой ключ на компьютере
sops и
age-keygenберём со страниц релизов на GitHub, на Windows —sops-v3.13.3.amd64.exeи архивage-v1.3.2-windows-amd64.zip. Ключ кладём туда, где sops найдёт его без переменных:mkdir -p ~/.config/sops/age && age-keygen -o ~/.config/sops/age/keys.txt # Linux mkdir -p "$APPDATA/sops/age" && age-keygen -o "$APPDATA/sops/age/keys.txt" # Windows, Git BashНа Windows ключ держим в профиле, а не на втором диске: файл получает права каталога, а у второго диска они по умолчанию дают читать его любой учётной записи компьютера. Предупреждение
age-keygen—writing secret key to a world-readable file— на Windows печатается всегда и о правах ничего не говорит. Копия закрытого ключа — в менеджере паролей..sops.yaml — для кого шифровать
На сервере,
sudo nano /opt/.sops.yaml. В файле только открытые ключи, он лежит в git:keys: - &owner age1zqfsfym3g0frgrmxkq9fzg34kw0w6x6x9rrf6mfhp8jz92m4t94smvzch4 # компьютер - &web1 age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvg # сервер creation_rules: - path_regex: '^secrets[/\\]' age: [*owner, *web1]Правило говорит: файл из
secrets/шифруем для обоих ключей. Путь sops сверяет от каталога.sops.yaml, на Windows — через\, поэтому разделитель —[/\\], в одинарных кавычках. Сам.sops.yamlsops ищет вверх от текущего каталога: команды работают из любого места клона, а вне клона — нет.Хук: открытый файл в secrets/ не пройдёт
sudo install -d /opt/.githooks, затемsudo nano /opt/.githooks/pre-commit:#!/bin/sh # Файл из secrets/ коммитим, только если он расшифровывается: открытый или испорченный не пройдёт. # Ошибку sops не выводим: в ней бывает открытое значение git -c core.quotePath=false diff --cached --name-only --diff-filter=ACMR -- secrets/ | { fail=0 while IFS= read -r f; do git show ":$f" | sops decrypt --filename-override "$f" >/dev/null 2>&1 && continue echo "pre-commit: $f не расшифровывается, причина — sops decrypt $f >/dev/null" >&2 fail=1 done [ $fail = 0 ] || echo "pre-commit: новый файл шифруем — sops encrypt -i <файл>, правим — sops edit <файл>" >&2 exit $fail }sudo chmod 755 /opt/.githooks/pre-commit sudo git -C /opt config core.hooksPath .githooksХук берёт файл из индекса — то, что уйдёт в коммит, — и пробует расшифровать.
sops filestatusдля этого не годится: файл, в который дописали открытую строку, он называет зашифрованным. А ошибку sops хук прячет, потому что на такой строке sops печатает в ошибке само значение:Input string lab-only-smtp does not match sops' data format.Расшифровывает хук ключом того, кто коммитит: на компьютере — ключом владельца, на сервере — ключом сервера.
core.hooksPath— настройка клона, в git она не попадает: на компьютере её включаем отдельно.git commit --no-verifyхук обходит: он страхует от ошибки, от намеренного коммита открытого файла он не защитит.Скрипт деплоя secrets.sh
sudo nano /opt/scripts/secrets.sh:#!/bin/bash # Расшифровывает /opt/secrets: <каталог>/.env — в /opt/<каталог>/.env (600), остальное — в /srv/secrets/<каталог>/ (400) set -u cd /opt/secrets umask 077 shopt -s dotglob nullglob for f in */*; do d=${f%%/*} if [ "${f#*/}" = .env ]; then out=/opt/$d/.env mode=600 else out=/srv/secrets/$f mode=400 install -d -m 700 "/srv/secrets/$d" fi # --output при сбое прежний файл не трогает, а «> файл» обнулил бы его. # Ошибку sops не выводим: в ней бывает открытое значение, а вывод deploy.sh уходит в Healthchecks.io if ! sops decrypt --output "$out" "$f" 2>/dev/null; then echo "secrets.sh: $f не расшифрован, подробно — sudo sops decrypt /opt/secrets/$f >/dev/null" >&2 exit 1 fi chmod "$mode" "$out" donesudo chmod 700 /opt/scripts/secrets.sh- Права — как в «Секреты в Docker-стеках»: каталоги 700, файлы 400,
.env600. Новый файл--outputсоздаёт с правами 644, отсюдаumask 077иchmod. - Файлы, которых нет в git, скрипт не трогает: ключ SSH для Kopia в
/srv/secrets/kopia/остаётся на месте. - Подкаталоги в
secrets/<каталог>/скрипт не разбирает: файлы лежат на одном уровне, как в/srv/secrets/.
- Права — как в «Секреты в Docker-стеках»: каталоги 700, файлы 400,
.gitignore пропускает secrets/
В белом списке
/opt/.gitignoreрядом с!/scripts/:!/.sops.yaml !/.githooks/И в конец файла:
# Зашифрованные sops — всё из secrets/; открытый файл туда не пустит хук !/secrets/ !/secrets/**.envи*.keyбелый список запрещает на любой глубине. Строки в конце разрешают вsecrets/всё: побеждает последнее подходящее правило. Файлы внутриsecrets/проверяет хук.Шифруем и коммитим на сервере
cd /opt sudo install -d secrets/deploy secrets/gatus sudo cp /srv/secrets/deploy/hc-url secrets/deploy/ sudo cp gatus/.env secrets/gatus/ sudo sops encrypt -i secrets/deploy/hc-url sudo sops encrypt -i secrets/gatus/.env sudo git add .gitignore .sops.yaml .githooks scripts/secrets.sh secrets sudo git commit -m "secrets: sops, deploy и gatus" sudo git pushКаталог из
/srv/secrets/копируем вsecrets/под тем же именем,.envстека — вsecrets/<стек>/.env. Ключ SSH для Kopia в git не кладём: у каждого сервера он свой, на новом его создаёт «Переезд на новый сервер». Коммит проходит через хук — его проверил ключ сервера. В git теперь шифротекст:sudo git -C /opt show HEAD:secrets/gatus/.env | head -1 # NTFY_TOPIC=ENC[AES256_GCM,data:Ry7UoYwtqg0uGhMbo2WeTQ==,iv:…Правим на компьютере
git pull git config core.hooksPath .githooks sops edit secrets/gatus/.env git commit -am "gatus: новый топик ntfy" git pushsops editрасшифровывает файл во временный, открывает редактор —SOPS_EDITOR,EDITOR, без них vim, nano или vi — и после закрытия шифрует обратно, а временный файл удаляет. У файла без расширения в редакторе — само значение. Новый.env— тоже черезsops edit: файла нет, и sops создаёт его сразу зашифрованным, с примером внутри. Новый файл без расширения пишем открытым и шифруемsops encrypt -i: пока он открытый, хук не пустит его в коммит.Выкладываем на сервере
sudo git -C /opt pull && sudo /opt/scripts/secrets.sh cd /opt/gatus && sudo docker compose up -d --force-recreateСтек пересоздаём:
.envcompose читает, когда создаёт контейнер. Файл Docker secret--outputпереписывает на месте, и в контейнере он новый сразу, но приложение могло прочитать его только при старте. С автоматическим деплоем этот шаг делаетdeploy.sh— следующий раздел.
Если сервер забирает git сам
С «Деплой без SSH» секрет подтягивается через git вместе с остальным, если deploy.sh умеет его
расшифровывать. Четыре правки:
# Отдельный файл после git контейнер не видит: изменилось не только compose — пересоздаём
- elif git diff --name-only "$old" "$new" -- "$s" | grep -qvx "$s/docker-compose.yaml"; then
+ elif git diff --name-only "$old" "$new" -- "$s" "secrets/$s" | grep -qvx "$s/docker-compose.yaml"; then
…
git merge -q --ff-only "$new" || fail "git merge не прошёл"
+ # Секреты — до стеков. Не расшифровались — откат, как у стека
+ if ! git diff --quiet "$old" "$new" -- secrets && ! out=$(/opt/scripts/secrets.sh 2>&1); then
+ git reset -q --hard "$old"
+ /opt/scripts/secrets.sh >/dev/null 2>&1
+ echo "$new" > "$failed"
+ fail "Секреты ${new:0:7} не расшифровались, вернули ${old:0:7}:
+$out"
+ fi
…
- for s in $(git diff --name-only "$old" "$new" | cut -d/ -f1 | sort -u); do
+ for s in $(git diff --name-only "$old" "$new" | sed 's|^secrets/||' | cut -d/ -f1 | sort -u); do
…
git reset -q --hard "$old"
+ /opt/scripts/secrets.sh >/dev/null 2>&1
for d in $touched; do up "$d" >/dev/null 2>&1; done
- Изменились файлы в
secrets/—secrets.shрасшифровывает их до перезапуска стеков. secrets/gatus/.envотносится к стекуgatus: он попадает в список изменённых и пересоздаётся с--force-recreate.- Секрет не расшифровался — откат, как у стека, который не поднялся: коммит назад, прежние секреты обратно. В
Healthchecks.io —
Секреты f72479b не расшифровались, вернули cd3048cи строкаsecrets.shс именем файла, дальше каждый запуск —f72479b не поднялся, ждём следующего коммита, пока на GitHub не придёт исправление. - Стек не поднялся — при откате возвращаются и прежние секреты.
deploy.service уже задаёт Environment=HOME=/root: без него sops из службы ключа не найдёт. После updatekeys
меняются все файлы в secrets/, и deploy.sh пересоздаёт все стеки с секретами.
Новый сервер
При переезде и для второго сервера секреты подтягиваются через git, когда у нового сервера появился свой ключ.
-
На новом сервере — шаги «sops и age на сервере» и «Ключ сервера».
age-keygenпечатает открытый ключ. -
На компьютере дописываем его в
.sops.yamlи перешифровываем все файлы для нового списка получателей:# в .sops.yaml: - &new age1jt0hu4qn6lcdsxx6rn0q2qnphnqyllj9u5rx2pn9cd607vf52q6qxx4elx # age: [*owner, *web1, *new] sops updatekeys -y $(git ls-files secrets) git commit -am "secrets: ключ нового сервера" && git pushThe following changes will be made to the file's groups: Group 1 age1zqfsfym3g0frgrmxkq9fzg34kw0w6x6x9rrf6mfhp8jz92m4t94smvzch4 age1whhd3q4wx570htrwx658f9dl2zk76wgcj4k2ytr02mdk2xvmeq5qxvcvvg +++ age1jt0hu4qn6lcdsxx6rn0q2qnphnqyllj9u5rx2pn9cd607vf52q6qxx4elxupdatekeysшифрует ключ данных для нового списка, значения в файлах остаются прежними.git ls-filesберёт и.env, который шаблонsecrets/*/*в bash пропускает. -
На новом сервере —
git cloneиз «Переезд на новый сервер» иsudo /opt/scripts/secrets.sh. Порядок сrestore.shлюбой: файлы из gitsecrets.shвсё равно запишет поверх, аrestore.shс--skip-existingуже выложенные не трогает.
Ключ сервера в бэкап не нужен: новый сервер получает свой. Старый сервер удалили — убираем его ключ из .sops.yaml
и снова запускаем updatekeys. Если ключ мог утечь, этого мало: updatekeys не меняет ключ данных, и утёкший ключ
вместе с блоком получателя из старой версии файла откроет значения, добавленные позже. Тогда нужны sops rotate -i
для каждого файла и смена самих секретов у сервисов: старые версии из истории git утёкший ключ читает всегда.
Варианты
| Что | Как | Что учесть |
|---|---|---|
| ключ хоста SSH вместо ключа age у сервера | получатель в .sops.yaml — строка из /etc/ssh/ssh_host_ed25519_key.pub без комментария; расшифровка — с SOPS_AGE_SSH_PRIVATE_KEY_FILE=/etc/ssh/ssh_host_ed25519_key |
сам sops из ключей SSH смотрит только ~/.ssh/id_ed25519 и ~/.ssh/id_rsa: без переменной ключа хоста он не найдёт, и её нужно задать и в терминале, и в службе |
| несекретное оставить открытым | суффикс _unencrypted у имени (port_unencrypted: 8080) или encrypted_regex в правиле .sops.yaml |
открытые значения тоже охраняет sops_mac: правка руками — MAC mismatch, правим через sops edit |
| один репозиторий на несколько серверов | правило на каждый каталог: path_regex: '^web1[/\\]secrets[/\\]' с age: [*owner, *web1], так же для web2 |
сервер расшифровывает только свои файлы, на чужой — Failed to get the data key. На пути у каждого сервера свой репозиторий («Переезд на новый сервер»), правило одно |
Если не работает
sops encrypt -i пишет error loading config: no matching creation rules found
- Причина
- Путь файла не подходит под
path_regexв.sops.yaml: файл лежит не вsecrets/, или на Windows в выражении разделитель/, а sops сверяет путь через\. - Делаем
- Файл кладём в
secrets/<каталог>/, разделитель в выражении —[/\\], в одинарных кавычках:'^secrets[/\\]'.
sops encrypt пишет config file not found, or has no creation rules, and no keys provided through command line options
- Причина
- Команду запустили вне клона:
.sops.yamlsops ищет вверх от текущего каталога, а не от каталога файла. - Делаем
- Переходим в клон — на сервере
cd /opt— и повторяем. Из подкаталога клона тоже работает.
В Healthchecks.io — Секреты f72479b не расшифровались, вернули cd3048c, а sudo sops decrypt этого файла пишет Failed to get the data key required to decrypt the SOPS file и identity did not match any of the recipients
- Причина
- Ключа сервера нет среди получателей файла: его добавили в
.sops.yaml, аupdatekeysне запустили, или файл зашифровали с--ageв обход правил. Хук на компьютере такой файл пропускает: ключ владельца среди получателей есть. Получатели файла перечислены в той же ошибке. - Делаем
- На компьютере
sops updatekeys -y secrets/gatus/extra— получатели станут как в.sops.yaml, — коммит и push. Следующий запускdeploy.shвыложит секреты.
secrets.sh из службы systemd пишет, что файл не расшифрован, а с sudo в терминале всё работает
- Причина
- Служба без
User=запускается безHOME, и sops не находит/root/.config/sops/age/keys.txt:sops decryptв такой службе пишет$HOME is not defined; user config directory could not be determined. - Делаем
Environment=HOME=/rootв разделе[Service]. Вdeploy.serviceиз «Деплой без SSH» он уже есть.
sops decrypt для .env пишет parsing time "2026-11-12T13:31:42Z\x0d": extra text: "\x0d"
- Причина
- В клоне
.envс переводами строк CRLF: git на Windows сcore.autocrlf=trueтак записывает файлы в рабочий каталог. YAML и файлы без расширения с CRLF расшифровываются,.env— нет. - Делаем
- В
.gitattributes—* text=auto eol=lf, на пути он есть с первого коммита. Если строку добавили позже, файлы, которые уже лежат в клоне,git pullне переписывает:rm secrets/gatus/.env && git checkout -- secrets/gatus/.env.
Пароль из .env не подходит, хотя в sops edit он верный
- Причина
- Редактор на Windows сохранил текст с CRLF, и sops оставил
\rв конце каждого значения. Зашифрованный файл при этом цел, и хук его пропускает. - Делаем
- В редакторе — переводы строк LF, правим заново. Проверка:
sops decrypt secrets/gatus/.env | tr -cd '\r' | wc -c— 0.
Новое значение уже в /opt/gatus/.env или /srv/secrets/, а сервис работает со старым
- Причина
.envcompose читает, когда создаёт контейнер. Файл Docker secretsecrets.shпереписывает на месте, в контейнере он новый сразу, но приложение могло прочитать его только при старте.- Делаем
cd /opt/gatus && sudo docker compose up -d --force-recreate. У Docker secret описание сервиса не меняется, и без--force-recreateконтейнер не пересоздаётся.
Как проверить
На компьютере хук не пускает открытый файл:
printf 'A=1\n' > secrets/gatus/test.env
git add secrets/gatus/test.env && git commit -m test
# pre-commit: secrets/gatus/test.env не расшифровывается, причина — sops decrypt secrets/gatus/test.env >/dev/null
# pre-commit: новый файл шифруем — sops encrypt -i <файл>, правим — sops edit <файл>
git rm -q --cached secrets/gatus/test.env && rm secrets/gatus/test.env
На сервере выложено то же, что в git. Сравниваем, не выводя значений на экран:
sudo sops decrypt /opt/secrets/gatus/.env | sudo cmp - /opt/gatus/.env && echo совпадает
sudo sops decrypt /opt/secrets/deploy/hc-url | sudo cmp - /srv/secrets/deploy/hc-url && echo совпадает
sudo stat -c '%a %n' /srv/secrets/deploy/hc-url /opt/gatus/.env
# 400 /srv/secrets/deploy/hc-url
# 600 /opt/gatus/.env