Fix GitHub Actions workflow for HACS distribution

- Handle repository initialization for first-time setup
- Improve branch handling (main/master compatibility)
- Add better error reporting and logging
- Create setup documentation for HACS distribution

The workflow now properly handles:
- Non-existent distribution repositories
- Branch creation and naming consistency
- Robust error handling with detailed feedback

Co-authored-by: Amp <amp@ampcode.com>
Amp-Thread-ID: https://ampcode.com/threads/T-25786ba9-89f5-4416-ae1d-9fd85bde1c2d

Author: dougrathbone

.github/workflows/hacs-distribution.yml

@@ -140,28 +140,59 @@ jobs:
         This distribution repository is automatically updated when releases are tagged in the main repository.
         EOF
         
-    - name: Checkout distribution repository
-      uses: actions/checkout@v4
-      with:
-        repository: ${{ env.DISTRIBUTION_REPO }}
-        token: ${{ secrets.HACS_DEPLOY_TOKEN }}
-        path: hacs-repo
-        
-    - name: Update distribution repository
+    - name: Checkout or initialize distribution repository
       run: |
-        # Clear existing content (except .git)
-        find hacs-repo -mindepth 1 -name '.git' -prune -o -type f -exec rm {} + 2>/dev/null || true
-        find hacs-repo -mindepth 1 -name '.git' -prune -o -type d -exec rm -rf {} + 2>/dev/null || true
+        echo "🔍 Attempting to checkout distribution repository: ${{ env.DISTRIBUTION_REPO }}"
         
-        # Copy new distribution files
-        cp -r distribution/* hacs-repo/
-        
-        cd hacs-repo
+        # Try to checkout the existing repository
+        if git clone https://${{ secrets.HACS_DEPLOY_TOKEN }}@github.com/${{ env.DISTRIBUTION_REPO }}.git hacs-repo 2>/dev/null; then
+          echo "✅ Distribution repository exists, checked out successfully"
+          cd hacs-repo
+          
+          # Ensure we're on the main branch (GitHub's default)
+          if git show-ref --verify --quiet refs/heads/main; then
+            git checkout main
+            echo "✅ Switched to main branch"
+          elif git show-ref --verify --quiet refs/heads/master; then
+            git checkout master
+            # Rename master to main for consistency
+            git branch -m master main
+            echo "✅ Renamed master branch to main"
+          else
+            git checkout -b main
+            echo "✅ Created main branch"
+          fi
+        else
+          echo "⚠️  Distribution repository does not exist or is empty"
+          echo "📝 Creating local repository structure for first-time setup..."
+          
+          mkdir hacs-repo
+          cd hacs-repo
+          
+          # Initialize new repository
+          git init --initial-branch=main
+          git remote add origin https://${{ secrets.HACS_DEPLOY_TOKEN }}@github.com/${{ env.DISTRIBUTION_REPO }}.git
+          
+          echo "✅ Initialized local repository with main branch"
+        fi
         
         # Configure git
         git config user.name 'HACS Distribution Bot'
         git config user.email 'actions@github.com'
         
+        echo "✅ Git configuration complete"
+        
+    - name: Update distribution repository
+      run: |
+        cd hacs-repo
+        
+        # Clear existing content (except .git)
+        find . -mindepth 1 -name '.git' -prune -o -type f -exec rm {} + 2>/dev/null || true
+        find . -mindepth 1 -name '.git' -prune -o -type d -exec rm -rf {} + 2>/dev/null || true
+        
+        # Copy new distribution files
+        cp -r ../distribution/* .
+        
         # Add all files
         git add .
         
@@ -173,12 +204,26 @@ jobs:
         
         # Commit and push
         git commit -m "Release v${{ steps.version.outputs.version }}
-        
+
         Automated release from main repository
         Source: ${{ github.repository }}@${{ github.sha }}
         "
         
-        git push origin main
+        echo "📤 Pushing to distribution repository..."
+        
+        # Push to main branch, creating it if it doesn't exist on remote
+        if git push -u origin main; then
+          echo "✅ Successfully pushed to distribution repository"
+        else
+          echo "❌ Failed to push to distribution repository"
+          echo "🔍 Checking remote repository status..."
+          git remote -v
+          echo "📋 Current branch:"
+          git branch -a
+          echo "📊 Repository status:"
+          git status
+          exit 1
+        fi
         
     - name: Create GitHub Release
       if: startsWith(github.ref, 'refs/tags/')

docs/setup-hacs-distribution.md

@@ -0,0 +1,91 @@
+# HACS Distribution Setup Guide
+
+This guide explains how to set up the HACS distribution repository and GitHub Actions workflow.
+
+## Prerequisites
+
+Before running the automated distribution workflow, you need to:
+
+### 1. Create the Distribution Repository
+
+1. Go to GitHub and create a new **public** repository:
+   - Repository name: `cgateweb-hacs`
+   - Description: "C-Gate Web Bridge - Home Assistant Addon (HACS Distribution)"
+   - Make it **public** (required for HACS)
+   - **Do not** initialize with README, .gitignore, or license (the workflow will populate it)
+
+### 2. Create a Personal Access Token
+
+1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Generate a new token with these permissions:
+   - `repo` (Full control of private repositories)
+   - `workflow` (Update GitHub Action workflows)
+3. Copy the token (you won't see it again!)
+
+### 3. Add GitHub Secrets
+
+In the main repository (`dougrathbone/cgateweb`):
+
+1. Go to Settings → Secrets and variables → Actions
+2. Click "New repository secret"
+3. Add the secret:
+   - Name: `HACS_DEPLOY_TOKEN`
+   - Value: The personal access token from step 2
+
+## How the Workflow Works
+
+The GitHub Actions workflow (`.github/workflows/hacs-distribution.yml`) is triggered when:
+
+- A version tag is pushed (e.g., `v1.0.0`)
+- Manually triggered via GitHub Actions UI
+
+### Workflow Steps:
+
+1. **Checkout & Test**: Gets the source code and runs tests
+2. **Build Distribution**: Creates the addon structure in `distribution/`
+3. **Initialize Repository**: Clones or initializes the HACS distribution repo
+4. **Deploy Content**: Copies distribution files to the HACS repo
+5. **Create Release**: Creates a GitHub release in the distribution repo
+
+## First Run
+
+When you run the workflow for the first time:
+
+1. **Create the distribution repository** on GitHub (step 1 above)
+2. **Add the deploy token** as a secret (steps 2-3 above)
+3. **Tag a version** in the main repo:
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+4. **Monitor the workflow** in the Actions tab
+
+The workflow will automatically:
+- Initialize the distribution repository
+- Set up the main branch
+- Populate it with the addon files
+- Create the first release
+
+## Troubleshooting
+
+### "Repository not found" error
+- Ensure the distribution repository exists and is public
+- Verify the `HACS_DEPLOY_TOKEN` has the correct permissions
+
+### "Branch main doesn't exist" error
+- The workflow now handles this automatically
+- It will create the main branch if it doesn't exist
+
+### Permission denied
+- Check that the personal access token has `repo` and `workflow` permissions
+- Ensure the token is added as `HACS_DEPLOY_TOKEN` in repository secrets
+
+## Manual Testing
+
+To test the workflow without creating a tag:
+
+1. Go to Actions → "Build and Deploy HACS Distribution"
+2. Click "Run workflow"
+3. Select the branch and click "Run workflow"
+
+This will create a development build with a timestamp-based version.