.gitea/workflows/build-and-publish.yml

@@ -39,13 +39,18 @@ jobs:
         uses: docker/metadata-action@v5
         with:
           images: ${{ env.REGISTRY }}/${{ github.repository }}
+          # Semantic version tags are produced from pushed v* git tags.
+          # `latest` follows the newest non-prerelease release via latest=auto.
+          # Branch and SHA tags are kept for traceability of non-release builds.
           tags: |
-            type=ref,event=branch
-            type=ref,event=pr
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=ref,event=branch
+            type=ref,event=pr
             type=sha
-            type=raw,value=latest,enable={{is_default_branch}}
+          flavor: |
+            latest=auto
 
       - name: Build and push
         uses: docker/build-push-action@v6

README.md

@@ -55,8 +55,11 @@ registry write permission on most Gitea instances. Create the token under an
 account with write access to the target package namespace, then store it as a
 repository Actions secret named `PACKAGES_TOKEN`.
 
-The published image is `<gitea-host>/<owner>/<repo>`, tagged by branch, semver
+The published image is `<gitea-host>/<owner>/<repo>`. Pushing a `v*` git tag
-(for `v*` tags), commit SHA, and `latest` on the default branch.
+produces semantic-version tags (`{{version}}`, `{{major}}.{{minor}}`,
+`{{major}}`), and `latest` is moved to that build when it is not a pre-release.
+Non-release builds on `main` are tagged by branch name and commit SHA only, so
+`latest` always points at the most recent release rather than the newest commit.
 
 ## Dependency updates