feat: generate the gt command reference from gitea/cli

update_cli_docs.sh runs gt's own generator and lays the pages out for the
site: one directory per command group, front matter, titles, sidebar
order, fenced help text and rewritten links. --released succeeds while no
series is documented. A weekly workflow proposes updates like the runner's.

Signed-off-by: bircni <[email protected]>

.gitea/workflows/update_cli_reference.yaml

@@ -0,0 +1,114 @@
+name: update cli reference
+
+on:
+  schedule:
+    - cron: '45 3 * * 1' # every Monday at 03:45
+  workflow_dispatch:
+
+env:
+  # main is protected, so the update is proposed as a pull request from this branch
+  BOT_BRANCH: bot/update-cli-reference
+  BASE_BRANCH: main
+  # the develop cli docs follow the main branch of gitea/cli, every documented
+  # release series follows its newest stable tag. The value is used unquoted, so
+  # the glob is expanded by the shell of each step, which drops it with nullglob
+  # as long as no series is documented.
+  TARGET_DIRS: cli-docs/reference cli-docs_versioned_docs/version-*/reference
+
+jobs:
+  update-cli-reference:
+    if: github.repository == 'gitea/docs'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: main
+          # pushing uses DEPLOY_TOKEN, keep the ephemeral job token out of .git/config
+          persist-credentials: false
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
+        with:
+          go-version: 'stable'
+          cache: false
+      - name: regenerate the cli reference pages
+        run: |
+          set -euo pipefail
+          ./update_cli_docs.sh main cli-docs/reference
+          ./update_cli_docs.sh --released
+      - name: verify the generated files
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          # the pages are generated from gt's command tree, so a broken
+          # generator would silently drop pages or leave them almost empty
+          for dir in $TARGET_DIRS; do
+            echo "checking $dir"
+            grep -q '^gt \[flags\]' "$dir/index.md"
+            grep -q '^gt issue create \[flags\]' "$dir/issue/create.md"
+            grep -q -- '--no-input' "$dir/help/environment.md"
+            test "$(find "$dir" -name '*.md' | wc -l)" -gt 100
+          done
+      - name: push bot branch
+        id: bot_branch
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+
+          # git status also sees the pages of a new command, which git diff does not
+          if [ -z "$(git status --porcelain -- $TARGET_DIRS)" ]; then
+            echo "the cli reference is already up to date"
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ -z "$DEPLOY_TOKEN" ]; then
+            echo "secrets.DEPLOY_TOKEN is missing, cannot push the update"
+            exit 1
+          fi
+          remote="https://x-access-token:$DEPLOY_TOKEN@${GITHUB_SERVER_URL#*://}/$GITHUB_REPOSITORY.git"
+
+          # skip if an open bot branch already carries exactly these files
+          if git fetch --quiet --depth=1 "$remote" "refs/heads/$BOT_BRANCH" 2>/dev/null; then
+            if git diff --quiet FETCH_HEAD -- $TARGET_DIRS; then
+              echo "$BOT_BRANCH already proposes this cli reference"
+              echo "changed=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          fi
+
+          git config user.name "Gitea Bot"
+          git config user.email "[email protected]"
+          git switch --create "$BOT_BRANCH"
+          git add --all -- $TARGET_DIRS
+          git commit -m "Update the cli reference pages"
+          # force push: the branch is always rebuilt on top of the current main
+          git push --force "$remote" "HEAD:refs/heads/$BOT_BRANCH"
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+      - name: create pull request
+        if: steps.bot_branch.outputs.changed == 'true'
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          cat > pull.json <<EOF
+          {
+            "base": "$BASE_BRANCH",
+            "head": "$BOT_BRANCH",
+            "title": "Update the cli reference pages",
+            "body": "Automated update of the generated gt reference pages from gitea/cli (main for the develop docs, the newest stable tag for every documented series), opened by the \"update cli reference\" scheduled workflow."
+          }
+          EOF
+
+          code="$(curl --silent --show-error --output pull-response.json --write-out '%{http_code}' \
+            -X POST "${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls" \
+            -H "Authorization: token $DEPLOY_TOKEN" \
+            -H 'Content-Type: application/json' \
+            --data @pull.json)"
+
+          case "$code" in
+            201) echo "pull request created" ;;
+            409) echo "an open pull request for $BOT_BRANCH already exists, it now points at the new commit" ;;
+            *) echo "unexpected response $code:"; cat pull-response.json; exit 1 ;;
+          esac