From 15ff61903840ae469bcc79df0cc17d41d86c1263 Mon Sep 17 00:00:00 2001 From: Rohan Kumar Date: Tue, 28 Jan 2025 22:27:43 +0530 Subject: [PATCH] ci : Add github action workflow to generate documentation preview (#2) Add github action to generate documentation preview by publishing gh-pages on an external repository. This change adds four new github action workflows: - Documentation Preview Request: A workflow that would run on the pull request and generate website and upload it as a github artifact. - Documentation Preview Generator: A workflow that would get triggered on the completion of `Documentation Preview Request` workflow and it would download the uploaded artifact and deploy the content to github repository configured in secrets. - Documentation Preview Cleanup Request: A workflow that would run on pull request upon the closing event of pull request. It would save pull request number as an artifact and upload it. - Documentation Preview Cleanup: A workflow that would get triggered on the completion of `Documentation Preview Cleanup Request` workflow and it would download the uploaded artifact and update the github repository and remove the generated preview directory. Signed-off-by: Rohan Kumar --- .../documentation-preview-cleanup-request.yml | 22 +++++++++ .../documentation-preview-cleanup.yml | 41 ++++++++++++++++ .../documentation-preview-request.yml | 30 ++++++++++++ .github/workflows/documentation-preview.yml | 49 +++++++++++++++++++ 4 files changed, 142 insertions(+) create mode 100644 .github/workflows/documentation-preview-cleanup-request.yml create mode 100644 .github/workflows/documentation-preview-cleanup.yml create mode 100644 .github/workflows/documentation-preview-request.yml create mode 100644 .github/workflows/documentation-preview.yml diff --git a/.github/workflows/documentation-preview-cleanup-request.yml b/.github/workflows/documentation-preview-cleanup-request.yml new file mode 100644 index 0000000..6696948 --- /dev/null +++ b/.github/workflows/documentation-preview-cleanup-request.yml @@ -0,0 +1,22 @@ +name: Documentation Preview Cleanup Request + +on: + pull_request: + types: + - closed + +jobs: + on-close: + runs-on: ubuntu-24.04 + + steps: + - name: Save the GH context in an artifact + env: + GH_CONTEXT: ${{ toJSON(github) }} + run: echo $GH_CONTEXT > github_context.json + - name: Upload the GH context artifact + uses: actions/upload-artifact@v4 + with: + name: github-context + path: github_context.json + diff --git a/.github/workflows/documentation-preview-cleanup.yml b/.github/workflows/documentation-preview-cleanup.yml new file mode 100644 index 0000000..c198b8b --- /dev/null +++ b/.github/workflows/documentation-preview-cleanup.yml @@ -0,0 +1,41 @@ +name: Documentation Preview Cleanup + +on: + workflow_run: + workflows: [Documentation Preview Cleanup Request] + types: + - completed + +env: + PREVIEW_PUBLISH_USERNAME: ${{ secrets.PREVIEW_PUBLISH_USERNAME }} + PREVIEW_PUBLISH_REPOSITORY: ${{ secrets.PREVIEW_PUBLISH_REPOSITORY }} + PREVIEW_PUBLISH_BRANCH: ${{ secrets.PREVIEW_PUBLISH_BRANCH }} + PREVIEW_PUBLISH_TOKEN: ${{ secrets.PREVIEW_PUBLISH_TOKEN }} + +jobs: + on-close: + if: ${{ github.event.workflow_run.conclusion == 'success' }} + runs-on: ubuntu-24.04 + + steps: + - name: Download artifact + uses: actions/download-artifact@v4 + with: + name: cleanup-info + path: . + run-id: ${{ github.event.workflow_run.id }} + github-token: ${{ github.token }} + - name: Configure Git + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "github-actions[bot]@users.noreply.github.com" + - name: Extract Pull Request ID from artifact + run: echo "PR_NUMBER=$(jq '.event.pull_request.number' github_context.json)" >> $GITHUB_ENV + - name: Push updates to external repository + run: | + git clone https://${PREVIEW_PUBLISH_USERNAME}:${PREVIEW_PUBLISH_TOKEN}@github.com/${PREVIEW_PUBLISH_USERNAME}/${PREVIEW_PUBLISH_REPOSITORY}.git -b ${PREVIEW_PUBLISH_BRANCH} + cd ${PREVIEW_PUBLISH_REPOSITORY} + rm -rf preview/pr/${PR_NUMBER} + git add preview/pr/${PR_NUMBER} + git commit -am "cleanup (preview) : remove preview for Pull Request #${PR_NUMBER}" + git push origin ${PREVIEW_PUBLISH_BRANCH} diff --git a/.github/workflows/documentation-preview-request.yml b/.github/workflows/documentation-preview-request.yml new file mode 100644 index 0000000..fe1b963 --- /dev/null +++ b/.github/workflows/documentation-preview-request.yml @@ -0,0 +1,30 @@ +name: Documentation Preview Request + +on: + pull_request: {} + +jobs: + build: + runs-on: ubuntu-24.04 + + steps: + - name: Check out repository code + uses: actions/checkout@v4 + - name: Build docs + run: CI=true make build_docs + - name: Check links in docs + run: make docs_check_links + - name: Create robots.txt + run: | + echo "User-agent: *" > ./public/robots.txt + echo "Disallow: /" >> ./public/robots.txt + - name: Save the GH context in an artifact + env: + GH_CONTEXT: ${{ toJSON(github) }} + run: echo $GH_CONTEXT > ./public/github_context.json + - name: Upload GitHub artifact + uses: actions/upload-artifact@v4 + with: + name: documentation + path: public + diff --git a/.github/workflows/documentation-preview.yml b/.github/workflows/documentation-preview.yml new file mode 100644 index 0000000..6d633e5 --- /dev/null +++ b/.github/workflows/documentation-preview.yml @@ -0,0 +1,49 @@ +name: Documentation Preview Generator + +on: + workflow_run: + workflows: [Documentation Preview Request] + types: + - completed + +env: + PREVIEW_PUBLISH_USERNAME: ${{ secrets.PREVIEW_PUBLISH_USERNAME }} + PREVIEW_PUBLISH_REPOSITORY: ${{ secrets.PREVIEW_PUBLISH_REPOSITORY }} + PREVIEW_PUBLISH_BRANCH: ${{ secrets.PREVIEW_PUBLISH_BRANCH }} + PREVIEW_PUBLISH_TOKEN: ${{ secrets.PREVIEW_PUBLISH_TOKEN }} + +jobs: + documentation-preview: + if: ${{ github.event.workflow_run.conclusion == 'success' }} + runs-on: ubuntu-24.04 + steps: + - name: Download artifact + uses: actions/download-artifact@v4 + with: + name: documentation + path: ./artifact + run-id: ${{ github.event.workflow_run.id }} + github-token: ${{ github.token }} + - name: Extract Pull Request ID from artifact + run: | + echo "PR_NUMBER=$(jq '.event.pull_request.number' ./artifact/github_context.json)" >> $GITHUB_ENV + echo "PR_SHA=$(jq -r '.event.pull_request.head.sha' ./artifact/github_context.json | cut -c 1-7)" >> $GITHUB_ENV + rm ./artifact/github_context.json + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + with: + personal_token: ${{ env.PREVIEW_PUBLISH_TOKEN }} + external_repository: ${{ env.PREVIEW_PUBLISH_USERNAME }}/${{ env.PREVIEW_PUBLISH_REPOSITORY }} + publish_dir: ./artifact + publish_branch: ${{ env.PREVIEW_PUBLISH_BRANCH }} + destination_dir: preview/pr/${{ env.PR_NUMBER }}/${{ env.PR_SHA}} + commit_message: "deploy documentation preview to GitHub Pages for PR #${{ env.PR_NUMBER }}" + + - name: Comment PR with preview link + run: | + PREVIEW_URL="https://${PREVIEW_PUBLISH_USERNAME}.github.io/${PREVIEW_PUBLISH_REPOSITORY}/preview/pr/${PR_NUMBER}/${PR_SHA}/index.html" + curl -s --request POST \ + --url "https://api.github.com/repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \ + --header "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \ + --header "Content-Type: application/json" \ + --data "{\"body\":\"🚀 Documentation preview: ${PREVIEW_URL}\"}"