Docs automation fixes

.github/workflows/docs-branch-create.yml

@@ -1,4 +1,3 @@
----
 # .github/workflows/docs-branch-create.yml
 #
 # Place this file in:
@@ -25,9 +24,9 @@
 #   There is only one active docs branch at a time. This branch becomes the
 #   base target for all Docs/Needed PRs in the new cycle
 #   (see docs-needed.yml in the code repos).
- 
+
 name: Create Next Version Docs Branch
- 
+
 on:
   pull_request:
     types: [closed]
@@ -38,7 +37,7 @@ on:
         description: 'Branch name to simulate merging (e.g. v11.6-documentation)'
         required: true
         type: string
- 
+
 jobs:
   create-next-version-branch:
     name: Create docs branch for next milestone
@@ -57,7 +56,7 @@ jobs:
        github.event.pull_request.head.repo.full_name == github.repository &&
        startsWith(github.event.pull_request.head.ref, 'v') &&
        endsWith(github.event.pull_request.head.ref, '-documentation'))
- 
+
     steps:
       # 0. Generate a short-lived read token scoped to mattermost/mattermost
       #    for milestone reads. Uses the shared changelog read app so the token
@@ -66,10 +65,10 @@ jobs:
         id: token
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
-          app-id: ${{ vars.CHANGELOG_READ_CLIENT_ID }}
+          client-id: ${{ vars.CHANGELOG_READ_CLIENT_ID }}
           private-key: ${{ secrets.CHANGELOG_READ_PRIVATE_KEY }}
           repositories: mattermost
- 
+
       # 1. Strict branch name validation
       #    The job-level if: is a broad pre-filter (GitHub Actions expressions
       #    do not support regex). This step enforces the exact pattern
@@ -86,7 +85,7 @@ jobs:
           fi
           echo "Branch validated: ${MERGED_BRANCH}"
           echo "Looking for the next open milestone in mattermost/mattermost..."
- 
+
       # 2. Find the next open milestone in mattermost/mattermost
       #    "Next" means the earliest open milestone whose version is strictly
       #    greater than the branch that just merged. Filtering by version
@@ -106,11 +105,15 @@ jobs:
           MERGED_MAJOR="${BASH_REMATCH[1]}"
           MERGED_MINOR="${BASH_REMATCH[2]}"
           echo "Merged: v${MERGED_MAJOR}.${MERGED_MINOR} — looking for the next open milestone..."
- 
+
           # Find open milestones with a version strictly greater than the merged
           # branch. Sort by due date (nulls last) then title; take the first.
           # --arg passes MERGED_MAJOR/MINOR as strings; tonumber converts inside jq.
+          # --paginate emits one JSON array per page. -s slurps all pages into
+          # a single outer array; add flattens [[page1...],[page2...]] → [...].
+          # Without -s, sort_by|first runs once per page — wrong across pages.
           JQ_FILTER='
+            add |
             [ .[] |
               select(
                 .state == "open" and
@@ -131,36 +134,36 @@ jobs:
             first |
             .title
           '
-
+
+          # Pipe to standalone jq with --arg — gh api does not support --arg.
           NEXT_TITLE=$(gh api repos/mattermost/mattermost/milestones \
             --paginate \
-            --jq "$JQ_FILTER" \
-            --arg maj "$MERGED_MAJOR" \
-            --arg min "$MERGED_MINOR")
-
+            | jq -rs --arg maj "$MERGED_MAJOR" --arg min "$MERGED_MINOR" \
+                "$JQ_FILTER")
+
           if [ -z "$NEXT_TITLE" ] || [ "$NEXT_TITLE" == "null" ]; then
             echo "::warning::No open milestone found with version >" \
               "v${MERGED_MAJOR}.${MERGED_MINOR} in mattermost/mattermost - no branch created."
             echo "found=false" >> "$GITHUB_OUTPUT"
             exit 0
           fi
- 
+
           # Derive the docs branch name: extract vMAJOR.MINOR, append -documentation
           # e.g. "v11.7.0" -> "v11.7-documentation"
           VERSION=$(echo "$NEXT_TITLE" | grep -oE 'v[0-9]+\.[0-9]+' | head -1)
- 
+
           if [ -z "$VERSION" ]; then
             echo "::error::Could not parse a vMAJOR.MINOR version from milestone '${NEXT_TITLE}'."
             exit 1
           fi
- 
+
           DOCS_BRANCH="${VERSION}-documentation"
- 
+
           echo "found=true" >> "$GITHUB_OUTPUT"
           echo "title=$NEXT_TITLE" >> "$GITHUB_OUTPUT"
           echo "branch=$DOCS_BRANCH" >> "$GITHUB_OUTPUT"
           echo "Next milestone: $NEXT_TITLE -> docs branch: $DOCS_BRANCH"
- 
+
       # 3. Create the branch in mattermost/docs
       - name: Create docs branch
         id: create_branch
@@ -172,24 +175,24 @@ jobs:
           # Check whether the branch already exists (idempotent)
           EXISTS=$(gh api "repos/mattermost/docs/branches/${BRANCH}" \
             --jq '.name' 2>/dev/null || echo "")
- 
+
           if [ -n "$EXISTS" ]; then
             echo "created=false" >> "$GITHUB_OUTPUT"
             echo "::notice::Branch '${BRANCH}' already exists in mattermost/docs - nothing to do."
             exit 0
           fi
- 
+
           # Branch from the tip of master
           SHA=$(gh api repos/mattermost/docs/branches/master --jq '.commit.sha')
- 
+
           gh api repos/mattermost/docs/git/refs \
             --method POST \
             -f "ref=refs/heads/${BRANCH}" \
             -f "sha=${SHA}"
- 
+
           echo "created=true" >> "$GITHUB_OUTPUT"
           echo "Created branch '${BRANCH}' in mattermost/docs from master (${SHA})"
- 
+
       # 4. Post a summary
       - name: Summary
         if: steps.milestone.outputs.found == 'true'

.github/workflows/docs-pr-sync.yml

@@ -1,4 +1,3 @@
----
 # .github/workflows/docs-pr-sync.yml
 #
 # Place this file in:
@@ -22,9 +21,9 @@
 #   and updates labels on the original dev PR:
 #     Removes Docs/Needed
 #     Adds    Docs/Done
- 
+
 name: "Docs PR Sync - Update Dev PR Labels on Close"
- 
+
 on:
   pull_request:
     types: [closed]
@@ -34,7 +33,7 @@ on:
         description: 'Docs branch name to simulate closing (e.g. docs/mattermost-pr-1234)'
         required: true
         type: string
- 
+
 jobs:
   sync-labels:
     name: "Remove Docs/Needed, Add Docs/Done on dev PR"
@@ -48,7 +47,7 @@ jobs:
       github.event_name == 'workflow_dispatch' ||
       (startsWith(github.event.pull_request.head.ref, 'docs/') &&
        github.event.pull_request.head.repo.full_name == github.repository)
- 
+
     steps:
       # 0. Generate a short-lived write token scoped to the three engineering
       #    repos. Uses the shared changelog write app so the token is not tied
@@ -57,13 +56,13 @@ jobs:
         id: token
         uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
-          app-id: ${{ vars.CHANGELOG_PR_CLIENT_ID }}
+          client-id: ${{ vars.CHANGELOG_PR_CLIENT_ID }}
           private-key: ${{ secrets.CHANGELOG_PR_PRIVATE_KEY }}
           repositories: >-
             mattermost,
             mattermost-mobile,
             desktop
- 
+
       # 1. Parse dev PR reference from branch name
       #    Branch format: docs/<repo-name>-pr-<number>
       #    e.g. docs/mattermost-pr-1234      -> mattermost/mattermost#1234
@@ -81,15 +80,15 @@ jobs:
           fi
           REPO_NAME="${BASH_REMATCH[1]}"
           PR_NUMBER="${BASH_REMATCH[2]}"
- 
+
           FULL_REPO="mattermost/${REPO_NAME}"
- 
+
           echo "repo_name=$REPO_NAME" >> "$GITHUB_OUTPUT"
           echo "full_repo=$FULL_REPO" >> "$GITHUB_OUTPUT"
           echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
- 
+
           echo "Dev PR resolved to: ${FULL_REPO}#${PR_NUMBER}"
- 
+
       # 2. Update labels on the dev PR
       #    Docs/Done is applied whether the docs PR was merged OR closed without
       #    merging. An abandoned docs PR means the developer is handling docs
@@ -104,20 +103,20 @@ jobs:
           DOCS_PR_MERGED: ${{ github.event.pull_request.merged }}
         run: |
           echo "Updating labels on ${DEV_REPO}#${DEV_PR}..."
- 
+
           # Remove Docs/Needed (soft-fail - label may already be absent)
           if gh pr edit "$DEV_PR" --repo "$DEV_REPO" \
                --remove-label "Docs/Needed" 2>/dev/null; then
             echo "  Removed Docs/Needed"
           else
             echo "  Docs/Needed not present or could not be removed - continuing"
           fi
- 
+
           # Add Docs/Done (hard-fail - this must succeed)
           # Applied for both merged and closed-without-merging; see comment above.
           gh pr edit "$DEV_PR" --repo "$DEV_REPO" --add-label "Docs/Done"
           echo "  Added Docs/Done"
- 
+
       # 3. Comment on the dev PR
       #    Skipped for workflow_dispatch: there is no real docs PR being closed,
       #    so github.event.pull_request.number is empty and the link would be broken.
@@ -135,10 +134,10 @@ jobs:
           else
             STATUS="closed without merging"
           fi
- 
+
           DOCS_LINK="[mattermost/docs#${DOCS_PR_NUMBER}]"
           DOCS_LINK="${DOCS_LINK}(https://github.com/mattermost/docs/pull/${DOCS_PR_NUMBER})"
- 
+
           gh pr comment "$DEV_PR" \
             --repo "$DEV_REPO" \
             --body "The associated docs PR ${DOCS_LINK} has been **${STATUS}**. Label updated: Docs/Needed -> Docs/Done."