From d4520835c98ce20fd01c5787ab8d436462f0ef6c Mon Sep 17 00:00:00 2001
From: fhoekstra <32362869+fhoekstra@users.noreply.github.com>
Date: Sun, 24 May 2026 00:11:31 +0200
Subject: [PATCH 1/2] docs: Add example for dealing with compromised key

The order of operations in this scenario is very specific and error-prone. It would make sense to document this right here in this project.

Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com>
---
 content/en/docs/_index.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md
index 2008b76..89d0218 100644
--- a/content/en/docs/_index.md
+++ b/content/en/docs/_index.md
@@ -1860,6 +1860,19 @@ You can also specify these options in the `.sops.yaml` config file.
 > and `--unencrypted-comment-regex` are mutually exclusive and
 > cannot all be used in the same file.
 
+### Rotating secrets after a public key in a key group has been compromised
+
+First, remove the key from the key group in `.sops.yaml`, then run the following for each sops-encrypted file:
+
+``` sh
+sops updatekeys secret.sops.yaml
+sops rotate --in-place secret.sops.yaml
+```
+
+This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the data key is encrypted with a key that the compromised key still has access to.
+
+Only after this is done, should you start rotating the actual passwords, API keys and other secrets that are encrypted inside `secret.sops.yaml`. Otherwise, if you put in new credentials before completing this step, the compromised key would still have access to those.
+
 ## Config file format
 
 This section describes the format of the SOPS config file.

From 385f60cc6b70ea15f062ba595d8481a9b722b194 Mon Sep 17 00:00:00 2001
From: fhoekstra <32362869+fhoekstra@users.noreply.github.com>
Date: Sun, 24 May 2026 09:16:44 +0200
Subject: [PATCH 2/2] Add small clarifications to key rotation example

Signed-off-by: fhoekstra <32362869+fhoekstra@users.noreply.github.com>
---
 content/en/docs/_index.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md
index 89d0218..94dcdb2 100644
--- a/content/en/docs/_index.md
+++ b/content/en/docs/_index.md
@@ -1860,9 +1860,9 @@ You can also specify these options in the `.sops.yaml` config file.
 > and `--unencrypted-comment-regex` are mutually exclusive and
 > cannot all be used in the same file.
 
-### Rotating secrets after a public key in a key group has been compromised
+### Rotating secrets after a key in a key group has been compromised
 
-First, remove the key from the key group in `.sops.yaml`, then run the following for each sops-encrypted file:
+First, remove the key from the key group in `.sops.yaml`, then run the following for each sops-encrypted file (only `secret.sops.yaml` in this example):
 
 ``` sh
 sops updatekeys secret.sops.yaml
@@ -1871,6 +1871,8 @@ sops rotate --in-place secret.sops.yaml
 
 This ensures that *first* the compromised key is removed from the list of keys that has access to the per-file data key, and only *then* rotates the data key. If done in the wrong order, the data key is encrypted with a key that the compromised key still has access to.
 
+Running `sops rotate` periodically is recommended anyways.
+
 Only after this is done, should you start rotating the actual passwords, API keys and other secrets that are encrypted inside `secret.sops.yaml`. Otherwise, if you put in new credentials before completing this step, the compromised key would still have access to those.
 
 ## Config file format