fix: update openapi sync workflow to eda (#16588)

In particular, this brings two important changes:
- rather than opening a new PR every time it runs, it uses a stable
  branch name updating its content instead; this means that at most
  there is one open PR per target branch
- a new secret "OPENAPI_SPEC_PR_REVIEW_TEAM" is introduced to specify
  the name of the github team to notify when creating new PRs; this
  helps to make sure that PRs are reviewed

.github/workflows/spec-sync-on-merge.yml

@@ -112,18 +112,16 @@ jobs:
           cp "./schema.json" "spec-repo/controller.json"
           echo "✅ Updated spec-repo/controller.json"
 
-      - name: Create PR in spec repo
+      - name: Create or update PR in spec repo
         if: steps.compare.outputs.has_diff == 'true'
         working-directory: spec-repo
         env:
           GH_TOKEN: ${{ secrets.OPENAPI_SPEC_SYNC_TOKEN }}
           GPG_PRIVATE_KEY: ${{ secrets.OPENAPI_SPEC_SYNC_GPG_PRIVATE_KEY }}
-          COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
           SPEC_REPO: ansible-automation-platform/aap-openapi-specs
-          REF_NAME: ${{ github.ref_name }}
-          GITHUB_SHA_FULL: ${{ github.sha }}
-          GITHUB_REPO: ${{ github.repository }}
-          IS_NEW_FILE: ${{ steps.compare.outputs.is_new_file }}
+          SPEC_PR_REVIEW_TEAM: ${{ secrets.OPENAPI_SPEC_PR_REVIEW_TEAM }}
+          SPEC_BRANCH: ${{ github.ref_name }}
+          SOURCE_COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
         run: |
           # Import GPG key and configure git for signed commits
           echo "$GPG_PRIVATE_KEY" | gpg --batch --import 2>/dev/null
@@ -140,59 +138,88 @@ jobs:
           # Configure git to use the token for push
           git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${SPEC_REPO}.git"
 
-          SHORT_SHA="${GITHUB_SHA_FULL:0:7}"
-          BRANCH_NAME="update-Controller-${REF_NAME}-${SHORT_SHA}"
+          # Use a stable branch name so we can reuse it across runs
+          BRANCH_NAME="auto/update-controller-${SPEC_BRANCH}"
+
+          # Check if there's already an open PR from this branch
+          EXISTING_PR=$(gh pr list \
+            --repo "$SPEC_REPO" \
+            --head "$BRANCH_NAME" \
+            --base "$SPEC_BRANCH" \
+            --state open \
+            --json number \
+            --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING_PR" ]; then
+            echo "📝 Found existing PR #${EXISTING_PR} - will update it"
+          else
+            echo "📝 No existing PR found - will create a new one"
+            # Clean up stale remote branch from a previously merged PR
+            git push origin --delete "$BRANCH_NAME" 2>/dev/null || true
+          fi
 
           git checkout -b "$BRANCH_NAME"
 
           # Add and commit changes
           git add "controller.json"
 
-          if [ "${IS_NEW_FILE}" == "true" ]; then
-            COMMIT_MSG="Add Controller OpenAPI spec for ${REF_NAME}"
+          if [ "${{ steps.compare.outputs.is_new_file }}" == "true" ]; then
+            COMMIT_MSG="Add Controller OpenAPI spec for ${SPEC_BRANCH}"
           else
-            COMMIT_MSG="Update Controller OpenAPI spec for ${REF_NAME}"
+            COMMIT_MSG="Update Controller OpenAPI spec for ${SPEC_BRANCH}"
           fi
 
-          git commit -m "${COMMIT_MSG}
+          git commit -m "$COMMIT_MSG
 
-          Synced from ${GITHUB_REPO}@${GITHUB_SHA_FULL}
-          Source branch: ${REF_NAME}
+          Synced from ${{ github.repository }}@${{ github.sha }}
+          Source branch: ${SPEC_BRANCH}
+          Spec repo branch: ${SPEC_BRANCH}
 
           Co-Authored-By: github-actions[bot] <github-actions[bot]@users.noreply.github.com>"
 
           # Push branch
-          git push origin "$BRANCH_NAME"
+          git push --force origin "$BRANCH_NAME"
 
-          # Create PR
-          PR_TITLE="[${REF_NAME}] Update Controller spec from merged commit"
-          PR_BODY="## Summary
+          # Create PR (commit message passed via env var to avoid script injection)
+          PR_TITLE="[${SPEC_BRANCH}] Update Controller spec from merged commit"
+          PR_BODY=$(cat <<EOF
+          ## Summary
           Automated OpenAPI spec sync from component repository merge.
 
-          **Source:** ${GITHUB_REPO}@${GITHUB_SHA_FULL}
-          **Branch:** \`${REF_NAME}\`
+          **Source:** ${{ github.repository }}@${{ github.sha }}
+          **Source Branch:** \`${SPEC_BRANCH}\`
+          **Spec Repo Branch:** \`${SPEC_BRANCH}\`
           **Component:** \`Controller\`
           **Spec File:** \`controller.json\`
 
           ## Changes
-          $(if [ "${IS_NEW_FILE}" == "true" ]; then echo "- 🆕 New spec file created"; else echo "- 📝 Spec file updated with latest changes"; fi)
+          $(if [ "${{ steps.compare.outputs.is_new_file }}" == "true" ]; then echo "- 🆕 New spec file created"; else echo "- 📝 Spec file updated with latest changes"; fi)
 
           ## Source Commit
           \`\`\`
-          ${COMMIT_MESSAGE}
+          ${SOURCE_COMMIT_MESSAGE}
           \`\`\`
 
           ---
-          🤖 This PR was automatically generated by the OpenAPI spec sync workflow."
+          🤖 This PR was automatically generated by the OpenAPI spec sync workflow.
+          EOF
+          )
 
-          gh pr create \
-            --repo "${SPEC_REPO}" \
-            --title "$PR_TITLE" \
-            --body "$PR_BODY" \
-            --base "${REF_NAME}" \
-            --head "$BRANCH_NAME"
-
-          echo "✅ Created PR in spec repo"
+          if [ -n "$EXISTING_PR" ]; then
+            gh pr edit "$EXISTING_PR" \
+              --repo "$SPEC_REPO" \
+              --body "$PR_BODY"
+            echo "✅ Updated existing PR #${EXISTING_PR}"
+          else
+            gh pr create \
+              --repo "$SPEC_REPO" \
+              --title "$PR_TITLE" \
+              --body "$PR_BODY" \
+              --base "$SPEC_BRANCH" \
+              --head "$BRANCH_NAME" \
+              --reviewer "$SPEC_PR_REVIEW_TEAM"
+            echo "✅ Created PR in spec repo"
+          fi
 
       - name: Report results
         if: always()