docs/.gitea/workflows/update_cli_reference.yaml

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