action.yml

name: Update `make docs` procedure
description: This action updates the `make docs` script and related Makefiles.
inputs:
  branch:
    default: update-make-docs
    description: Name of remote branch to push changes to. Should be unique to avoid conflict with user-created branches.
    required: false
  directory:
    default: docs
    description: Directory within the repository that should contain the script and related Makefiles.
    required: false
  pr_options:
    description: Additional command line options provided to the `gh pr create` command.
    required: false
  token:
    default: ${{ github.token }}
    description: Used to open the PR.
    required: false
  trace:
    default: false
    description: Print command traces.
    required: false
    type: boolean
runs:
  using: composite
  steps:
    - env:
        BRANCH: ${{ inputs.branch }}
        DIRECTORY: ${{ inputs.directory }}
        GH_TOKEN: ${{ inputs.token }}
        PR_OPTIONS: ${{ inputs.pr_options }}
        RUNNER_DEBUG: ${{ runner.debug || inputs.trace }}
      name: Update `make docs` procedure
      run: |
        set -euf -o pipefail

        if [[ -n "${RUNNER_DEBUG+x}" ]]; then
          set -x
        fi

        # fetch_files fetches the Makefiles and script and writes them to the provided directory.
        function fetch_files {
          local -r directory="$1"

          curl -s -Lo "${directory}/docs.mk" https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
          curl -s -Lo "${directory}/make-docs" https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
        }

        # commit adds and commits the updated files as the Grafanabot GitHub user.
        function commit {
          git add .
          git config --local user.email bot@grafana.com
          git config --local user.name grafanabot
          git commit --message 'Update `make docs` procedure'
        }

        PR_STATUS=$(gh pr view "${BRANCH}" --json state --jq .state || true)

        if [[ "${PR_STATUS}" == OPEN ]]; then
          gh pr checkout "${BRANCH}"

          fetch_files "${DIRECTORY}"

          if ! git diff --exit-code; then
            commit
            git push
          fi

          exit 0
        fi

        # Remove the remote branch if it exists because there is no PR associated with it.
        if git fetch origin "${BRANCH}"; then
          git push origin --delete "${BRANCH}"
        fi

        git checkout -b "${BRANCH}"

        fetch_files "${DIRECTORY}"

        # Use an array to ensure parsing of options that have spaces but that have been quoted in the input.
        # For example, pr_options: --label 'backport v10.0.x'
        OPTIONS_ARRAY=()
        while IFS= read -r -d '' arg; do
          if [[ -n "${arg}" ]]; then
            OPTIONS_ARRAY+=("$(printf '%s' "${arg}")")
          fi
        done < <(echo "${PR_OPTIONS}" | xargs printf '%s\0')

        read -r -d '' body << EOF || true
        To test the changes, run the following and browse to URL output by the script:

        \`\`\`console
        git fetch
        git checkout origin/update-make-docs
        cd docs
        make docs
        \`\`\`
        EOF

        if ! git diff --exit-code; then
          commit
          git push origin "refs/heads/${BRANCH}"
          # Set default options before the user-provided ones as later options appear to override earlier ones.
          # For example, in `gh pr create --web --title foo --title bar`, the resulting title is "bar".
          gh pr create --title  'Update `make docs` procedure' --body "${body}" "${OPTIONS_ARRAY[@]}"
        fi
      shell: bash