fix: address review comments (indentation, null check, diagram, permissions docs)

Author: uwe-mayer

ISSUE_LIFECYCLE.md

@@ -10,7 +10,7 @@ flowchart TD
     B --> C{Triage}
 
     C -->|clear & well-scoped| D[label: backlog]
-    C -->|unclear scope| E[label: needs-refinement]
+    C -->|unclear scope| E[labels: needs-refinement + backlog]
     C -->|duplicate / out of scope / won't fix| F([Closed])
     C -->|missing info| G[label: needs-more-info]
 

workflows/issue-project-sync/action.yaml

@@ -35,7 +35,7 @@ runs:
             }
           }' -f org="$ORG" -F number="$PROJECT_NUMBER" --jq '.data.organization.projectV2.id')
 
-        if [ -z "$PROJECT_ID" ]; then
+        if [ -z "$PROJECT_ID" ] || [ "$PROJECT_ID" = "null" ]; then
           echo "ERROR: Could not find project #${PROJECT_NUMBER} in org ${ORG}"
           exit 1
         fi

workflows/issue-triage/README.md

@@ -4,21 +4,26 @@ A reusable composite action that automatically labels new issues with `needs-tri
 
 ## Usage
 
-Create `.github/workflows/issue-triage.yml` in your repository:
+Create `.github/workflows/issue-triage.yaml` in your repository:
 
 ```yaml
 name: Issue Triage
 on:
   issues:
     types: [opened]
 
+permissions:
+  issues: write
+
 jobs:
   triage:
     runs-on: ubuntu-latest
     steps:
       - uses: cloudoperators/common/workflows/issue-triage@main
 ```
 
+> **Important:** The calling workflow **must** declare `permissions: issues: write`. Without this, the action will fail in repos/orgs where the default `GITHUB_TOKEN` is read-only.
+
 ## What it does
 
 1. Adds the `needs-triage` label to the newly opened issue
@@ -30,7 +35,8 @@ jobs:
 ## Prerequisites
 
 - The `needs-triage` label must exist in the repository (see label setup below)
-- The default `GITHUB_TOKEN` is sufficient — no additional secrets needed
+- The calling workflow must grant `permissions: issues: write`
+- The default `GITHUB_TOKEN` is sufficient for the token — no additional secrets needed
 
 ## Label Setup
 

workflows/issue-triage/action.yaml

@@ -3,7 +3,7 @@ description: Auto-label new issues with needs-triage and post a welcome comment
 
 inputs:
   GH_TOKEN:
-    description: 'GitHub token with issues write permission. Can use the default GITHUB_TOKEN.'
+    description: 'GitHub token with issues write permission. The calling workflow must grant permissions: issues: write.'
     required: false
     default: ${{ github.token }}
 
@@ -24,13 +24,17 @@ runs:
         GH_TOKEN: ${{ inputs.GH_TOKEN }}
         ISSUE_URL: ${{ github.event.issue.html_url }}
       run: |
-        gh issue comment "$ISSUE_URL" --body "Thanks for opening this issue! 🎉
+        BODY=$(cat <<'EOF'
+Thanks for opening this issue! 🎉
 
-        A maintainer will triage it within 5 business days. You can learn more about our issue workflow in the [Issue Lifecycle documentation](https://github.com/cloudoperators/common/blob/main/ISSUE_LIFECYCLE.md).
+A maintainer will triage it within 5 business days. You can learn more about our issue workflow in the [Issue Lifecycle documentation](https://github.com/cloudoperators/common/blob/main/ISSUE_LIFECYCLE.md).
 
-        In the meantime, please make sure you have provided:
-        - A clear problem statement
-        - Steps to reproduce (for bugs)
-        - Expected vs actual behavior
+In the meantime, please make sure you have provided:
+- A clear problem statement
+- Steps to reproduce (for bugs)
+- Expected vs actual behavior
 
-        This helps us route your issue faster."
+This helps us route your issue faster.
+EOF
+        )
+        gh issue comment "$ISSUE_URL" --body "$BODY"