Docs: Sync docs with website repo via GitHub Action (#20694)

* add GitHub action to sync docs with website repo * remove trigger-docs-update from circleci jobs * update access token
2025-02-25 18:55:37 -06:00 · 2019-12-04 14:36:50 +01:00 · 2019-12-04 14:36:50 +01:00 · c43aa3485c
commit c43aa3485c
parent 7a710737ae
7 changed files with 277 additions and 29 deletions
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@ -959,35 +959,6 @@ jobs:
      - store_artifacts:
          path: ./dist

-  trigger-docs-update:
-    docker:
-      - image: circleci/python:3.6.8
-    steps:
-      - checkout
-      - run:
-          name: ci job started
-          command: './scripts/ci-job-started.sh'
-      - run:
-          name: Trigger Docs update
-          command: |
-            if git diff --name-only HEAD^ | grep -q "^docs"; then
-              echo "Build URL:"
-              curl -s -u "$DOCS_CIRCLE_TOKEN:" \
-                -d build_parameters[CIRCLE_JOB]=pull-submodule-changes \
-                https://circleci.com/api/v1.1/project/github/grafana/docs.grafana.com/tree/master \
-              | jq .build_url
-            else
-              echo "-- no changes to docs files --"
-            fi
-      - run:
-          name: ci job failed
-          command: './scripts/ci-job-failed.sh'
-          when: on_fail
-      - run:
-          name: ci job succeeded
-          command: './scripts/ci-job-succeeded.sh'
-          when: on_success
-
  build-grafana-packages:
    docker:
      - image: circleci/node:12
--- a/.github/actions/gha-publish-to-git/Dockerfile
+++ b/.github/actions/gha-publish-to-git/Dockerfile
@ -0,0 +1,7 @@
+FROM alpine
+RUN apk update
+RUN apk add rsync git bash
+
+COPY entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/bin/bash", "/entrypoint.sh"]
--- a/.github/actions/gha-publish-to-git/LICENSE
+++ b/.github/actions/gha-publish-to-git/LICENSE
@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Sean Middleditch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/.github/actions/gha-publish-to-git/README.md
+++ b/.github/actions/gha-publish-to-git/README.md
@ -0,0 +1,60 @@
+publish-to-git
+==============
+
+[GitHub Action](https://github.com/features/actions) for publishing a directory
+and its contents to another git repository.
+
+This can be especially useful for publishing static website, such as with
+[GitHub Pages](https://pages.github.com/), from built files in other job
+steps, such as [Doxygen](http://www.doxygen.nl/) generated HTML files.
+
+**NOTE**: GitHub currently requires the use of a Personal Access Token for
+pushing to other repositories. Pushing to the current repository should work
+with the always-available GitHub Token (available via
+`{{ secrets.GITHUB_TOKEN }}`. If pushing to another repository, a Personal
+Access Token will need to be [created](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) and assigned to the
+workflow [secrets](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables).
+
+Inputs
+------
+
+- `repository`: Destination repository (default: current repository).
+- `branch`: Destination branch (required).
+- `host`: Destination git host (default: `github.com`).
+- `github_token`: GitHub Token (required; use `secrets.GITHUB_TOKEN`).
+- `github_pat`: Personal Access Token or other https credentials.
+- `source_folder`: Source folder in workspace to copy (default: workspace root).
+- `target_folder`: Target folder in destination branch to copy to (default: repository root).
+- `commit_author`: Override commit author (default: `{github.actor}@users.noreply.github.com`).
+- `commit_message`: Set commit message (default: `[workflow] Publish from [repository]:[branch]/[folder]`).
+- `dry_run`: Does not push if non-empty (default: empty).
+- `working_directory`: Location to checkout repository (default: random location in `${HOME}`)
+
+Outputs
+-------
+
+- `commit_hash`: SHA hash of the new commit.
+- `working_directory`: Working directory of git clone of repository.
+
+License
+-------
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+Usage Example
+-------------
+
+```yaml
+jobs:
+  publish:
+    - uses: actions/checkout@master
+    - run: |
+        sh scripts/build-doxygen-html.sh --out static/html
+    - uses: seanmiddleditch/gha-publish-to-git@master
+      with:
+        branch: gh-pages
+        github_token: '${{ secrets.GITHUB_TOKEN  }}'
+        github_pat: '${{ secrets.GH_PAT }}'
+        source_folder: static/html
+      if: success() && github.event == 'push'
+```
--- a/.github/actions/gha-publish-to-git/action.yml
+++ b/.github/actions/gha-publish-to-git/action.yml
@ -0,0 +1,60 @@
+---
+name: publish-to-git
+description: 'Publish files to a git repository'
+branding:
+  icon: 'git-commit'
+  color: 'blue'
+inputs:
+  repository:
+    description: 'Destination repository (default: current repository)'
+    default: ''
+  branch:
+    description: 'Destination branch'
+    required: true
+  host:
+    description: 'Destination git host'
+    default: 'github.com'
+  github_token:
+    description: 'GitHub Token (use `secrets.GITHUB_TOKEN`)'
+    required: true
+  github_pat:
+    description: 'Personal Access Token or other https credentials'
+    default: ''
+  source_folder:
+    description: 'Source folder in workspace to copy (default: workspace root)'
+    defaault: ''
+  target_folder:
+    description: 'Target folder in destination branch to copy to (default: repository root)'
+    default: ''
+  commit_author:
+    description: 'User Name <email@address> (default: [github.actor]@users.noreply.github.com)'
+    default: ''
+  commit_message:
+    description: 'Commit message (default: [workflow] Publish from [repository]:[branch]/[folder])'
+    default: ''
+  dry_run:
+    description: 'Do not push to repository (set to non-empty string to make dry-run)'
+    default: ''
+  working_directory:
+    description: 'Working directory for clone (default: random location in `${HOME}`)'
+    default: ''
+outputs:
+  commit_hash:
+    description: 'Hash of the new commit'
+  working_directory:
+    description: 'Working directory of temporary repository'
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  args:
+    - ${{ inputs.repository }}
+    - ${{ inputs.branch }}
+    - ${{ inputs.host }}
+    - ${{ inputs.github_token }}
+    - ${{ inputs.github_pat }}
+    - ${{ inputs.source_folder }}
+    - ${{ inputs.target_folder }}
+    - ${{ inputs.commit_author }}
+    - ${{ inputs.commit_message }}
+    - ${{ inputs.dry_run }}
+    - ${{ inputs.working_directory }}
--- a/.github/actions/gha-publish-to-git/entrypoint.sh
+++ b/.github/actions/gha-publish-to-git/entrypoint.sh
@ -0,0 +1,99 @@
+#/bin/bash
+
+# Name the Docker inputs.
+#
+INPUT_REPOSITORY="$1"
+INPUT_BRANCH="$2"
+INPUT_HOST="$3"
+INPUT_GITHUB_TOKEN="$4"
+INPUT_GITHUB_PAT="$5"
+INPUT_SOURCE_FOLDER="$6"
+INPUT_TARGET_FOLDER="$7"
+INPUT_COMMIT_AUTHOR="$8"
+INPUT_COMMIT_MESSAGE="$9"
+INPUT_DRYRUN="${10}"
+INPUT_WORKDIR="${11}"
+
+# Check for required inputs.
+#
+[ -z "$INPUT_BRANCH" ] && echo >&2 "::error::'branch' is required" && exit 1
+[ -z "$INPUT_GITHUB_TOKEN" -a -z "$INPUT_GITHUB_PAT" ] && echo >&2 "::error::'github_token' or 'github_pat' is required" && exit 1
+
+# Set state from inputs or defaults.
+#
+REPOSITORY="${INPUT_REPOSITORY:-${GITHUB_REPOSITORY}}"
+BRANCH="${INPUT_BRANCH}"
+HOST="${INPUT_GIT_HOST:-github.com}"
+TOKEN="${INPUT_GITHUB_PAT:-${INPUT_GITHUB_TOKEN}}"
+REMOTE="${INPUT_REMOTE:-https://${TOKEN}@${HOST}/${REPOSITORY}.git}"
+
+SOURCE_FOLDER="${INPUT_SOURCE_FOLDER:-.}"
+TARGET_FOLDER="${INPUT_TARGET_FOLDER}"
+
+REF="${GITHUB_BASE_REF:-${GITHUB_REF}}"
+REF_BRANCH=$(echo "${REF}" | rev | cut -d/ -f1 | rev)
+[ -z "$REF_BRANCH" ] && echo 2>&1 "No ref branch" && exit 1
+
+COMMIT_AUTHOR="${INPUT_AUTHOR:-${GITHUB_ACTOR} <${GITHUB_ACTOR}@users.noreply.github.com>}"
+COMMIT_MESSAGE="${INPUT_COMMIT_MESSAGE:-[${GITHUB_WORKFLOW}] Publish from ${GITHUB_REPOSITORY}:${REF_BRANCH}/${SOURCE_FOLDER}}"
+
+# Calculate the real source path.
+#
+SOURCE_PATH="$(realpath "${SOURCE_FOLDER}")"
+[ -z "${SOURCE_PATH}" ] && exit 1
+echo "::debug::SOURCE_PATH=${SOURCE_PATH}"
+
+# Let's start doing stuff.
+echo "Publishing ${SOURCE_FOLDER} to ${REMOTE}:${BRANCH}/${TARGET_FOLDER}"
+
+# Create a working directory; the workspace may be filled with other important
+# files.
+#
+WORK_DIR="${INPUT_WORKDIR:-$(mktemp -d "${HOME}/gitrepo.XXXXXX")}"
+[ -z "${WORK_DIR}" ] && echo >&2 "::error::Failed to create temporary working directory" && exit 1
+cd "${WORK_DIR}"
+
+# Initialize git repo and configure for remote access.
+#
+echo "Initializing repository with remote ${REMOTE}"
+git init || exit 1
+git config --local user.email "${GITHUB_ACTOR}@users.noreply.github.com" || exit 1
+git config --local user.name  "${GITHUB_ACTOR}" || exit 1
+git remote add origin "${REMOTE}" || exit 1
+git remote -v
+
+# Fetch initial (current contents).
+#
+echo "Fetching ${REMOTE}:${BRANCH}"
+git fetch --depth 1 origin "${BRANCH}" || exit 1
+git checkout -b "${BRANCH}" || exit 1
+git pull origin "${BRANCH}" || exit 1
+
+# Create the target directory (if necessary) and copy files from source.
+#
+TARGET_PATH="${WORK_DIR}/${TARGET_FOLDER}"
+echo "Populating ${TARGET_PATH}"
+mkdir -p "${TARGET_PATH}" || exit 1
+rsync -a --quiet --delete "${SOURCE_PATH}/" "${TARGET_PATH}" || exit 1
+
+# Create commit with changes.
+#
+echo "Creating commit"
+git add "${TARGET_PATH}" || exit 1
+git commit -m "${COMMIT_MESSAGE}" --author "${COMMIT_AUTHOR}" || exit 1
+COMMIT_HASH="$(git rev-parse HEAD)"
+echo "Created commit ${COMMIT_HASH}"
+
+# Publish output variables.
+#
+echo "::set-output name=commit_hash::${COMMIT_HASH}"
+echo "::set-output name=working_directory::${WORK_DIR}"
+
+# Push if not a dry-run.
+#
+if [ -z "${INPUT_DRYRUN}" ] ; then
+    echo "Pushing to ${REMOTE}:${BRANCH}"
+    git push origin "${BRANCH}" || exit 1
+else
+    echo "[DRY-RUN] Not pushing to ${REMOTE}:${BRANCH}"
+fi
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@ -0,0 +1,30 @@
+name: publish_docs
+
+on:
+  push:
+    branches:
+    - master
+    paths:
+    - 'docs/sources/**'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: publish-to-git
+      uses: ./.github/actions/gha-publish-to-git
+      id: publish
+      with:
+        repository: grafana/website
+        branch: docs-grafana
+        host: github.com
+        github_pat: '${{ secrets.GH_BOT_ACCESS_TOKEN }}'
+        source_folder: docs/sources
+        target_folder: content/docs/grafana/latest
+    - shell: bash
+      run: |
+        test -n "${{ steps.publish.outputs.commit_hash }}"
+        test -n "${{ steps.publish.outputs.working_directory }}"