From 2a2e69f04731ecf87f0f8e1c2107aa7afe9a8c31 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 27 Apr 2026 01:17:50 +0000
Subject: [PATCH] docs: document how to verify image signature in readme

Agent-Logs-Url: https://github.com/nextcloud/all-in-one/sessions/0127a09a-2fa8-4d32-9215-751016cf7db9

Co-authored-by: szaimen <42591237+szaimen@users.noreply.github.com>
---
 readme.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/readme.md b/readme.md
index 934357f6..2fb370e5 100644
--- a/readme.md
+++ b/readme.md
@@ -231,6 +231,9 @@ sudo docker run \
 > [!NOTE]
 > For production usage (and ease of upgrades and changes), we suggest using the example [Compose file](https://github.com/nextcloud/all-in-one/blob/main/compose.yaml) rather than `docker run`.
 
+> [!TIP]
+> You can optionally verify the cryptographic signature of the mastercontainer image before running it. See [How to verify the image signature?](#how-to-verify-the-image-signature)
+
 4. After the initial startup, open the Nextcloud AIO interface on port 8080 of this server **by IP address**, for example:
 ```txt
 https://192.168.5.5:8080
@@ -357,6 +360,7 @@ https://your-domain-that-points-to-this-server.tld:8443
     - [Update policy](#update-policy)
     - [How often are update notifications sent?](#how-often-are-update-notifications-sent)
     - [Huge docker logs](#huge-docker-logs)
+    - [How to verify the image signature?](#how-to-verify-the-image-signature)
 
 ### Where can I find additional documentation?
 Some of the documentation is available on [GitHub Discussions](https://github.com/nextcloud/all-in-one/discussions/categories/wiki).
@@ -1285,6 +1289,21 @@ AIO ships its own update notifications implementation. It checks if container up
 ### Huge docker logs
 If you should run into issues with huge docker logs, you can adjust the log size by following https://docs.docker.com/config/containers/logging/local/#usage. However for the included AIO containers, this should usually not be needed because almost all of them have the log level set to warn so they should not produce many logs.
 
+### How to verify the image signature?
+All AIO images published to `ghcr.io/nextcloud-releases/` are signed using [cosign](https://github.com/sigstore/cosign) with keyless signing via GitHub Actions (Sigstore). You can verify the signature of the mastercontainer image before running it by installing cosign and executing:
+
+```sh
+cosign verify \
+  --certificate-identity-regexp '^https://github\.com/nextcloud-releases/all-in-one/\.github/workflows/' \
+  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
+  ghcr.io/nextcloud-releases/all-in-one:latest
+```
+
+Replace `latest` with the tag you intend to run (e.g. `beta`). A successful verification prints the signing certificate details and exits with code 0. Any non-zero exit code means the signature could not be verified and you should **not** run that image.
+
+> [!NOTE]
+> AIO itself automatically verifies the cosign signature of every image it pulls from `ghcr.io/nextcloud-releases/` and refuses to pull images that fail verification. The manual command above lets you perform the same check independently before the initial `docker run`.
+
 <details>
 
 <summary>Badges</summary>