docs: add comprehensive troubleshooting guidance for membership issues

Enhanced user experience for blocked users with detailed troubleshooting:

Action improvements:
- Clear step-by-step troubleshooting in action output
- Enhanced GitHub annotations with direct links
- Better error messages explaining membership requirements

Workflow improvements:
- Added comments explaining access requirements
- Troubleshooting guidance in workflow logs
- Clear instructions for making membership public

README improvements:
- Dedicated troubleshooting section
- Step-by-step resolution guide
- Common issues and solutions
- Links to GitHub organization people page

This addresses cases like blocked workflow runs by providing clear
guidance on verifying and fixing organization membership visibility.

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

Co-Authored-By: Claude <[email protected]>

Author: sfreudenthaler

.github/actions/security/org-membership-check/README.md

@@ -49,10 +49,35 @@ The GitHub organization membership API works for both public and private members
 
 This approach successfully detects all dotCMS organization members regardless of their membership visibility setting, using only the default GITHUB_TOKEN without requiring additional secrets or configuration.
 
+## Troubleshooting
+
+If you're a dotCMS team member but getting blocked by the security gate:
+
+### Step 1: Verify Organization Membership
+1. Visit: https://github.com/orgs/dotCMS/people
+2. Look for your username in the member list
+3. If you're not listed, you need to be added to the organization
+
+### Step 2: Check Membership Visibility
+If you are listed but still blocked:
+1. Look for a "Make public" button next to your name
+2. Click it to make your membership public
+3. This allows the workflow to detect your membership
+
+### Step 3: Contact Organization Owners
+If you're not a member:
+- Contact a dotCMS organization owner to be added
+- Only organization members can trigger Claude workflows
+
+### Common Issues
+- **Private membership**: Most common cause - make membership public
+- **Not a member**: Contact org owners to be added
+- **Recent changes**: GitHub API may take a few minutes to reflect visibility changes
+
 ## Security Considerations
 
 - Only checks membership in the dotCMS organization (hardcoded)
-- Authorizes all organization members (both public and private)
+- Authorizes organization members (requires public membership visibility)
 - Logs authorization results without sensitive details
 - Uses default GITHUB_TOKEN (no additional secrets required)
-- No configuration or setup required for team members
+- Provides clear troubleshooting guidance for blocked users

.github/actions/security/org-membership-check/action.yml

@@ -43,22 +43,38 @@ runs:
         api_exit_code=$?
 
         if [ $api_exit_code -eq 0 ]; then
-          # HTTP 200/204: User is a member (public or private, but API accessible)
-          # For public members: HTTP 204 No Content (empty response but success)
-          # For private members: HTTP 204 No Content (empty response but success)
-          # The key is that we get a successful HTTP response (not 404)
+          # HTTP 204: User is a member (public or private)
           echo "✅ User ${{ inputs.username }} is a member of dotCMS"
           echo "is_member=true" >> $GITHUB_OUTPUT
           echo "membership_status=member" >> $GITHUB_OUTPUT
         else
-          # HTTP 404: Not a member
-          echo "❌ User ${{ inputs.username }} is not a member of dotCMS"
+          # HTTP 404: Not a member OR private membership not visible to GITHUB_TOKEN
+          echo "❌ User ${{ inputs.username }} is not authorized to trigger Claude workflows"
+          echo ""
+          echo "🔍 TROUBLESHOOTING STEPS:"
+          echo "1. Verify you are a member of the dotCMS organization:"
+          echo "   → Visit: https://github.com/orgs/dotCMS/people"
+          echo "   → You should see your username in the list"
+          echo ""
+          echo "2. If you are a member but have PRIVATE visibility:"
+          echo "   → Click 'Make public' next to your name"
+          echo "   → This allows the workflow to detect your membership"
+          echo ""
+          echo "3. If you are not a member:"
+          echo "   → Contact a dotCMS organization owner to be added"
+          echo "   → Only dotCMS organization members can trigger Claude workflows"
+          echo ""
           echo "is_member=false" >> $GITHUB_OUTPUT
           echo "membership_status=non-member" >> $GITHUB_OUTPUT
         fi
 
         # Log the result for debugging (without leaking membership details)
         membership_result=$(if [ "$(cat $GITHUB_OUTPUT | grep 'is_member=true')" ]; then echo "AUTHORIZED"; else echo "UNAUTHORIZED"; fi)
-        echo "::notice::Organization membership check result: $membership_result for ${{ inputs.username }}"
+
+        if [ "$membership_result" = "UNAUTHORIZED" ]; then
+          echo "::notice::❌ BLOCKED: ${{ inputs.username }} failed organization membership check. If you're a dotCMS team member, visit https://github.com/orgs/dotCMS/people and ensure your membership is PUBLIC."
+        else
+          echo "::notice::✅ AUTHORIZED: ${{ inputs.username }} is a dotCMS organization member"
+        fi
       env:
         GITHUB_TOKEN: ${{ github.token }}

.github/workflows/issue_comment_claude-code-review.yaml

@@ -20,6 +20,13 @@ on:
 
 jobs:
   # Security gate: Check if user is dotCMS organization member
+  #
+  # REQUIREMENTS FOR CLAUDE ACCESS:
+  # 1. Must be a member of the dotCMS organization
+  # 2. Membership must be set to PUBLIC visibility
+  #
+  # TROUBLESHOOTING: If blocked, visit https://github.com/orgs/dotCMS/people
+  # and ensure your membership is public (click "Make public" if needed)
   security-check:
     runs-on: ubuntu-latest
     permissions:
@@ -43,7 +50,13 @@ jobs:
           if [ "${{ steps.membership-check.outputs.is_member }}" = "true" ]; then
             echo "✅ Access granted: User is a dotCMS organization member"
           else
-            echo "❌ Access denied: User is not a dotCMS organization member"
+            echo "❌ Access denied: User failed dotCMS organization membership check"
+            echo ""
+            echo "📋 TROUBLESHOOTING: If you are a dotCMS team member:"
+            echo "   1. Visit https://github.com/orgs/dotCMS/people"
+            echo "   2. Ensure your membership is set to 'Public'"
+            echo "   3. If you're not listed, contact an organization owner"
+            echo ""
             echo "::warning::Unauthorized user attempted to trigger Claude workflow: ${{ github.event.comment.user.login || github.actor }}"
           fi