update

docs/maintainers/handbook.md

@@ -365,39 +365,42 @@ If we run `abra recipe upgrade wordpress` (at time of running), we end up with a
 
 ```
 $ abra recipe upgrade wordpress
-? upgrade to which tag? (service: app, image: wordpress, tag: 6.9.0) 6.9.1
-? upgrade to which tag? (service: db, image: mariadb, tag: 12.1) 12.2
-WARN unable to read tag for image atmoz/sftp, is it missing? skipping upgrade for ftp
+? upgrade to which tag? (service: app, image: wordpress, tag: 7.1.2) 7.1.3
+INFO tag upgraded and pinned from 7.1.2 to 7.1.3@sha256:8ecd8d8e374167ea22235acf30f80d1165b82f07ffa5bcef90c1cad8f7be251f for wordpress
+INFO no new versions available for mariadb, assuming 13.0 is the latest (use -a/--all-tags to see all anyway)
+INFO tag upgraded and pinned from 13.0 to 13.0@sha256:f1bba652ba57bea3099ca2fe1af692af537c27d96e0bcde39dce29e2ba1ec4f3 for mariadb
+WARN unable to parse atmoz/sftp, error was: version alpine is not supported (matched: ^[a-zA-Z]+$), skipping upgrade for ftp
 INFO wordpress currently has these unstaged changes 👇
 diff --git a/compose.yml b/compose.yml
-index b3c3871..07d0a54 100644
+index 591d157..99d5eb0 100644
 --- a/compose.yml
 +++ b/compose.yml
 @@ -3,7 +3,7 @@ version: "3.8"
  
  services:
    app:
--    image: "wordpress:6.9.0"
-+    image: "wordpress:6.9.1"
+-    image: "wordpress:7.1.2"
++    image: "wordpress:7.1.3@sha256:8ecd8d8e374167ea22235acf30f80d1165b82f07ffa5bcef90c1cad8f7be251f"
      volumes:
        - "wordpress_content:/var/www/html/wp-content/"
      networks:
-@@ -65,7 +65,7 @@ services:
-         - "coop-cloud.${STACK_NAME}.version=2.17.0+6.9.0"
+@@ -66,7 +66,7 @@ services:
+         - "coop-cloud.${STACK_NAME}.version=4.1.0+7.1.2"
  
    db:
--    image: "mariadb:12.1"
-+    image: "mariadb:12.2"
+-    image: "mariadb:13.0"
++    image: "mariadb:13.0@sha256:f1bba652ba57bea3099ca2fe1af692af537c27d96e0bcde39dce29e2ba1ec4f3"
      volumes:
        - "mariadb:/var/lib/mysql"
      networks:
-? commit changes? Yes
+? commit changes? (Y/n) 
 INFO committed changes as 'chore: update image tags'
 ```
 
 Here is a rundown of what happened:
 
 - `abra` queried the upstream container repositories of all the images listed in the Wordpress recipe configuration and checked if there are new tags available
+- `abra` also pulled the current manifest sha256 digest of the images at the new tags for that container
 - Once you make some choices on the prompt, `abra` will update the recipe configurations and show you the diff
 - If you choose to, a new commit containing the changes will be created
 

docs/maintainers/upgrade.md

@@ -74,6 +74,24 @@ version.
 `abra` will also warn Co-op Cloud operators about missing environment variables
 that are present in the recipe `.env.sample` but not in their app `.env` file.
 
+## Upstream versioning
+
+When upgrading a recipe automatically, abra will attempt to pin to a specific version
+of an upstream container image. The versions is a multi-architecture digest that is
+essentially immutable: if the upstream publishes a new image to that semantic version,
+abra won't use it until the recipe is upgraded again. This is a security feature: if a 
+maintainer publishes a new image with new contents, recipes won't use it unless 
+explicitly requested.
+
+Manifest images can be inspected manually:
+```
+docker buildx imagetools inspect 'gitlab/gitlab-ce:19.4.0-ce.0'
+
+Name: ...
+MediaType: ...
+Digest: sha256:...  <- This should go after gitlab-ce:19.4.0-ce.0@...
+```
+
 ## Creating new release notes
 
 Help other Co-op Cloud operators understand what they need to take care of when