(feature) add registry image check and workflow documentation

Added check_image_version job that verifies if Docker image already exists in registry using docker manifest inspect. This prevents redundant builds while handling registry cleanup scenarios. Also added explanatory comments above all jobs.

Key changes:
- New check_image_version job runs in parallel with check_version
- Uses docker manifest inspect for lightweight image existence check
- Build now uses OR logic: version changed OR image missing OR PR
- Both check jobs run independently for faster parallel execution
- Added comments explaining each job's purpose and build conditions

Build logic:
- Builds when version changed (new release)
- Builds when image missing from registry (handles cleanup)
- Always builds PRs (validation requirement)
- Skips only when version unchanged AND image exists

Benefits:
- Comprehensive checking of both git history and registry state
- Handles registry cleanup without manual intervention
- Clear documentation of workflow logic
- Parallel job execution for faster workflow runs

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.gitea/workflows/build.yml

@@ -11,6 +11,9 @@ on:
       - main
 
 jobs:
+  # Detects version changes in package.json compared to previous commit
+  # Outputs the current version and whether it changed from the last commit
+  # This is used to determine if a new release/build is needed
   check_version:
     runs-on: ubuntu-latest
     outputs:
@@ -58,9 +61,62 @@ jobs:
             echo "version_changed=false" >> $GITHUB_OUTPUT
           fi
 
+  # Verifies if Docker image with current version already exists in registry
+  # This prevents rebuilding the same version but allows pulls and version changes
+  # to always trigger new builds. Uses lightweight manifest inspect (no download)
+  check_image_version:
+    runs-on: ubuntu-latest
+    outputs:
+      image_exists: ${{ steps.manifest-check.outputs.image_exists }}
+      version: ${{ steps.version-read.outputs.version }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Read version from package.json
+        id: version-read
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Checking for image version: $VERSION"
+
+      - name: Login to Registry
+        run: |
+          echo "${{ secrets.PROFILE_REGISTRY_TOKEN }}" | docker login registry.budakova.org -u "${{ vars.PROFILE_REGISTRY_USERNAME }}" --password-stdin
+
+      - name: Check if image exists in registry
+        id: manifest-check
+        run: |
+          VERSION=${{ steps.version-read.outputs.version }}
+          IMAGE="registry.budakova.org/knee-cola/gitea-actions-demo-project:${VERSION}"
+
+          echo "Checking manifest for image: $IMAGE"
+
+          if docker manifest inspect "$IMAGE" &>/dev/null; then
+            echo "Image exists in registry"
+            echo "image_exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "Image does not exist in registry"
+            echo "image_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Summary
+        run: |
+          echo "Version: ${{ steps.version-read.outputs.version }}"
+          echo "Image exists: ${{ steps.manifest-check.outputs.image_exists }}"
+
+  # Builds and pushes Docker image to registry if conditions are met:
+  # - Version changed in package.json, OR
+  # - Image with current version doesn't exist in registry, OR
+  # - This is a pull request (always validate PRs)
+  # This ensures releases are built, missing images are created, and PRs are tested
   build:
-    needs: check_version
-    if: needs.check_version.outputs.version_changed == 'true' || github.event_name == 'pull_request'
+    needs: [check_version, check_image_version]
+    if: |
+      needs.check_version.outputs.version_changed == 'true' ||
+      needs.check_image_version.outputs.image_exists == 'false' ||
+      github.event_name == 'pull_request'
     runs-on: ubuntu-latest
 
     steps: