ci: harden Linear sync (error handling + rerun idempotency)

Author: feraio

.github/workflows/linear-sync.yml

@@ -14,8 +14,6 @@ permissions:
 jobs:
   create-linear-card:
     runs-on: ubuntu-latest
-    # Skip if the API key isn't configured yet, so forks / unconfigured repos
-    # don't produce noisy failing runs.
     if: ${{ github.event.issue != null }}
     steps:
       - name: Create Linear card
@@ -39,6 +37,14 @@ jobs:
             exit 0
           fi
 
+          # Idempotency: if this issue already has a Linear backlink comment
+          # (e.g. from a manual job re-run), do nothing.
+          if gh issue view "$ISSUE_NUMBER" --repo "$REPO" --json comments \
+               --jq '.comments[].body' 2>/dev/null | grep -q "Synced to Linear:"; then
+            echo "Issue already synced to Linear (marker found); skipping."
+            exit 0
+          fi
+
           # Build the Linear description (Markdown). jq handles all escaping.
           description=$(jq -n \
             --arg body "${ISSUE_BODY:-_No description provided._}" \
@@ -59,23 +65,37 @@ jobs:
                variables: { input: { teamId: $teamId, stateId: $stateId, title: $title, description: $description } }
              }')
 
-          response=$(curl -sS -X POST https://api.linear.app/graphql \
+          # Call Linear. Retry transient failures; fail loudly on HTTP errors.
+          # (Linear returns HTTP 200 even for GraphQL errors, so we also inspect .errors.)
+          http_code=$(curl -sS -o response.json -w '%{http_code}' \
+            --retry 3 --retry-all-errors --connect-timeout 10 --max-time 30 \
+            -X POST https://api.linear.app/graphql \
             -H "Authorization: $LINEAR_API_KEY" \
             -H "Content-Type: application/json" \
-            --data "$payload")
+            --data "$payload") || { echo "::error::Could not reach the Linear API."; exit 1; }
 
-          echo "Linear API response: $response"
+          response=$(cat response.json)
+          echo "Linear HTTP $http_code"
 
-          success=$(echo "$response" | jq -r '.data.issueCreate.success // false')
-          if [ "$success" != "true" ]; then
-            echo "::error::Linear card creation failed. Response: $response"
-            exit 1
+          if [ "$http_code" -lt 200 ] || [ "$http_code" -ge 300 ]; then
+            echo "::error::Linear returned HTTP $http_code: $response"; exit 1
+          fi
+          if echo "$response" | jq -e 'has("errors")' >/dev/null 2>&1; then
+            echo "::error::Linear GraphQL errors: $(echo "$response" | jq -c '.errors')"; exit 1
+          fi
+          if [ "$(echo "$response" | jq -r '.data.issueCreate.success // false')" != "true" ]; then
+            echo "::error::Linear issueCreate did not succeed: $response"; exit 1
           fi
 
-          linear_url=$(echo "$response" | jq -r '.data.issueCreate.issue.url')
-          linear_id=$(echo "$response" | jq -r '.data.issueCreate.issue.identifier')
+          linear_url=$(echo "$response" | jq -er '.data.issueCreate.issue.url') \
+            || { echo "::error::Linear response missing issue url: $response"; exit 1; }
+          linear_id=$(echo "$response" | jq -er '.data.issueCreate.issue.identifier') \
+            || { echo "::error::Linear response missing issue identifier: $response"; exit 1; }
           echo "Created Linear card $linear_id -> $linear_url"
 
-          # Link back on the GitHub issue so both sides are cross-referenced.
-          gh issue comment "$ISSUE_NUMBER" --repo "$REPO" \
-            --body "🔗 Synced to Linear: [$linear_id]($linear_url)"
+          # Link back on the GitHub issue. A failure here must NOT orphan the
+          # card silently: surface the URL so it can be recovered.
+          if ! gh issue comment "$ISSUE_NUMBER" --repo "$REPO" \
+                 --body "🔗 Synced to Linear: [$linear_id]($linear_url)"; then
+            echo "::warning::Linear card $linear_id ($linear_url) was created, but posting the backlink comment failed."
+          fi