Improve Forgejo Actions workflow documentation and error handling

- Add better secret configuration documentation with required status
- Include clear setup instructions for DOCKER_IMAGE_NAME secret
- Add validation check for missing DOCKER_IMAGE_NAME secret
- Improve troubleshooting section with Docker push errors
- Add helpful error messages for configuration issues

🤖 Generated with [Claude Code](https://claude.ai/code)

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

.forgejo/README.md

@@ -49,13 +49,15 @@ This directory contains Forgejo Actions workflows for the Baktainer project. For
 
 ## Required Secrets
 
-Configure these secrets in your Forgejo repository settings:
+Configure these secrets in your Forgejo repository settings (`/{owner}/{repository}/settings` → Repository → Secrets):
 
-| Secret | Description | Example |
+| Secret | Description | Example | Required |
-|--------|-------------|---------|
+|--------|-------------|---------|----------|
-| `DOCKER_USERNAME` | Docker Hub username | `jamez001` |
+| `DOCKER_USERNAME` | Docker Hub username | `jamez001` | ✅ Yes |
-| `DOCKER_PASSWORD` | Docker Hub password or token | `dckr_pat_...` |
+| `DOCKER_PASSWORD` | Docker Hub password or token | `dckr_pat_...` | ✅ Yes |
-| `DOCKER_IMAGE_NAME` | Docker image name | `jamez001/baktainer` |
+| `DOCKER_IMAGE_NAME` | Docker image name | `jamez001/baktainer` | ✅ Yes |
+
+**Important**: All three secrets must be configured for the workflow to succeed. Missing secrets will cause the build to fail with clear error messages.
 
 ## Configuration Requirements
 
@@ -129,7 +131,17 @@ git push origin feature-branch
    - **Auto-detects package manager** (apk, apt-get, yum, dnf) for maximum compatibility
    - **If still experiencing issues**: Check your Forgejo runner configuration and container image support
 
-2. **Working directory not found error**
+2. **Docker push reference format error**
+   ```
+   Error parsing reference: ":latest" is not a valid repository/tag: invalid reference format
+   ```
+   **Solutions**:
+   - **Missing secret**: Configure `DOCKER_IMAGE_NAME` secret in repository settings
+   - **Example value**: `jamez001/baktainer` (your Docker Hub username/repository)
+   - **Path**: Go to `/{owner}/{repository}/settings` → Repository → Secrets
+   - **Verify**: All three Docker secrets must be configured (USERNAME, PASSWORD, IMAGE_NAME)
+
+3. **Working directory not found error**
    ```
    OCI runtime exec failed: exec failed: unable to start container process: 
    chdir to cwd ("/workspace/james/baktainer/./app") set in config.json failed: 
@@ -140,7 +152,7 @@ git push origin feature-branch
    - The error occurred because `working-directory` was set before repository checkout
    - Repository must be cloned before changing to subdirectories
 
-3. **Actions not running**
+4. **Actions not running**
    - Check if Repository Actions are enabled
    - Verify Forgejo Runner is installed and running
    - Check workflow file syntax
@@ -150,12 +162,12 @@ git push origin feature-branch
    - Check Dockerfile syntax
    - Ensure runner has Docker access
 
-4. **Test failures**
+5. **Test failures**
    - Check Ruby version compatibility
    - Verify system dependencies in Alpine
    - Review test output in workflow logs
 
-5. **GitHub Actions compatibility**
+6. **GitHub Actions compatibility**
    - **Not applicable**: Current workflow uses only shell commands
    - **No external actions**: Maximum compatibility with any Forgejo runner
 

.forgejo/workflows/ci.yml

@@ -104,9 +104,20 @@ jobs:
         run: |
           IMAGE_NAME="${{ secrets.DOCKER_IMAGE_NAME }}"
           
+          # Check if IMAGE_NAME is set
+          if [ -z "${IMAGE_NAME}" ]; then
+            echo "❌ Error: DOCKER_IMAGE_NAME secret is not set"
+            echo "Please configure the DOCKER_IMAGE_NAME secret in your repository settings"
+            echo "Example: jamez001/baktainer"
+            exit 1
+          fi
+          
+          echo "📦 Pushing to Docker Hub as ${IMAGE_NAME}"
+          
           # Tag as latest
           docker tag baktainer-test "${IMAGE_NAME}:latest"
           docker push "${IMAGE_NAME}:latest"
+          echo "✅ Pushed ${IMAGE_NAME}:latest"
           
           # Tag with version if it's a tag
           if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then