From b59fbff5231cbcc88c9154c4bd0b5def5af613fe Mon Sep 17 00:00:00 2001 From: Neil Dewhurst Date: Fri, 5 Jan 2024 11:54:53 +0000 Subject: [PATCH] Use new GHA workflows (#828) Updates include: - Improved security - Enhanced comments with links to updated pages in the deployed HTML - Branch verification, including an option to check links and style --- .github/workflows/docs-branch-checks.yml | 55 ++++++++++++++++++ .github/workflows/docs-deploy-surge.yml | 53 +++++++++++++---- .github/workflows/docs-pr-checks.yml | 74 ++++++++++++++++++++++++ .github/workflows/docs-pr.yml | 30 ---------- .github/workflows/docs-teardown.yml | 20 +++++-- 5 files changed, 187 insertions(+), 45 deletions(-) create mode 100644 .github/workflows/docs-branch-checks.yml create mode 100644 .github/workflows/docs-pr-checks.yml delete mode 100644 .github/workflows/docs-pr.yml diff --git a/.github/workflows/docs-branch-checks.yml b/.github/workflows/docs-branch-checks.yml new file mode 100644 index 000000000..1f09367e4 --- /dev/null +++ b/.github/workflows/docs-branch-checks.yml @@ -0,0 +1,55 @@ +# This is an example of the docs-pr.yml workflow available from the recrwplay org +name: "Verify Branch" + +on: + # push: + # branches: + # - dev + # schedule: + # - cron: '00 16 * * *' + workflow_dispatch: + inputs: + html: + description: 'Generate HTML' + type: boolean + required: false + default: true + links: + description: 'Check links' + type: boolean + required: false + default: true + lint: + description: 'Lint docs' + type: boolean + required: false + default: true + +jobs: + + docs-build: + if: ${{ inputs.html }} + name: Generate HTML + uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@dev + with: + retain-artifacts: 14 + deploy-id: 0 + package-script: 'publish-verify' + cli-options: '--extension ./.docs-tools/extensions/antora/aliases-redirects' + + docs-verify: + name: Verify HTML + needs: docs-build + uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@dev + + docs-links: + if: ${{ inputs.links }} + name: Check links + needs: docs-build + uses: neo4j/docs-tools/.github/workflows/reusable-docs-links.yml@dev + + docs-lint: + if: ${{ inputs.lint }} + name: Lint docs + uses: neo4j/docs-tools/.github/workflows/reusable-docs-vale.yml@dev + \ No newline at end of file diff --git a/.github/workflows/docs-deploy-surge.yml b/.github/workflows/docs-deploy-surge.yml index 0eeec088d..ec2ad6fb8 100644 --- a/.github/workflows/docs-deploy-surge.yml +++ b/.github/workflows/docs-deploy-surge.yml @@ -1,32 +1,38 @@ # Use this starter workflow to deploy HTML generated by Antora to surge.sh # Docs are published at --.surge.sh -# By default, this workflow runs on completion of a workflow called "Verify PR" +# +# By default, this workflow runs on completion of a workflow called "Verify docs PR" +# # This workflow expects the triggering workflow to generate an artifact called "docs" - # - update the reference to "docs" and "docs.zip" in this workflow if your triggering workflow generates an artifact with a different name + name: "Deploy to surge" on: workflow_run: - workflows: ["Verify PR"] + workflows: ["Verify Docs PR"] types: - completed jobs: publish-docs: + # Uncomment this if statement to deploy only when the PR builds cleanly # if: github.event.workflow_run.conclusion == 'success' runs-on: ubuntu-latest steps: - name: "Download built documentation" - uses: actions/github-script@v6.0.0 + uses: actions/github-script@v6.4.1 + env: + RUN_ID: ${{ github.event.workflow_run.id }} + WORKSPACE: ${{ github.workspace }} with: script: | var artifacts = await github.rest.actions.listWorkflowRunArtifacts({ owner: context.repo.owner, repo: context.repo.repo, - run_id: ${{ github.event.workflow_run.id }}, + run_id: ${{ env.RUN_ID }}, }); var matchArtifact = artifacts.data.artifacts.filter((artifact) => { return artifact.name == "docs" @@ -38,7 +44,7 @@ jobs: archive_format: 'zip', }); var fs = require('fs'); - fs.writeFileSync('${{ github.workspace }}/docs.zip', Buffer.from(download.data)); + fs.writeFileSync('${{ env.WORKSPACE }}/docs.zip', Buffer.from(download.data)); - run: unzip docs.zip @@ -47,6 +53,15 @@ jobs: deployid=$(> "$GITHUB_OUTPUT" + + - id: get-deploy-url + env: + ORG: ${{ github.event.repository.owner.login }} + REPO: ${{ github.event.repository.name }} + DEPLOYID: ${{ steps.get-deploy-id.outputs.deploy-id }} + run: | + deployurl=$ORG-$REPO-$DEPLOYID.surge.sh + echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT - uses: actions/setup-node@v3 with: @@ -55,17 +70,35 @@ jobs: - name: Deploy docs to surge shell: bash env: + DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }} SURGE_TOKEN: "${{ secrets.DOCS_SURGE_TOKEN }}" run: | npm install -g surge - surge ./site ${{ github.event.repository.owner.login}}-${{ github.event.repository.name}}-${{ steps.get-deploy-id.outputs.deploy-id }}.surge.sh --token "$SURGE_TOKEN" + surge ./site $DEPLOY_URL --token "$SURGE_TOKEN" - - name: Comment on PR + # If the PR artifacts include a changelog file, add it to the PR as a comment + # The changelog contains links to new and changed files in the deployed docs + - name: Comment on PR (changelog) + if: ${{ hashFiles('changelog') != '' }} + uses: marocchino/sticky-pull-request-comment@v2 + with: + number: ${{ steps.get-deploy-id.outputs.deploy-id }} + recreate: true + header: docs-pr-changes + path: changelog + GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }} + + # If there's no changelog, add a generic comment to the PR + - name: Comment on PR (no changelog) + if: ${{ hashFiles('changelog') == '' }} + env: + DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }} uses: marocchino/sticky-pull-request-comment@v2 with: number: ${{ steps.get-deploy-id.outputs.deploy-id }} + header: docs-pr-changes message: | - This PR includes documentation updates. + Looks like you've updated the documentation! - You can view the updated docs at https://${{ github.event.repository.owner.login}}-${{ github.event.repository.name}}-${{ steps.get-deploy-id.outputs.deploy-id }}.surge.sh + Check out your changes at https://${{ env.DEPLOY_URL }} GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }} diff --git a/.github/workflows/docs-pr-checks.yml b/.github/workflows/docs-pr-checks.yml new file mode 100644 index 000000000..b4c1ff54a --- /dev/null +++ b/.github/workflows/docs-pr-checks.yml @@ -0,0 +1,74 @@ + +name: "Verify Docs PR" + +on: + pull_request: + branches: + - dev + +jobs: + + # Generate HTML + docs-build-pr: + uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@dev + with: + deploy-id: ${{ github.event.number }} + retain-artifacts: 14 + pageList: true + + # Parse the json log output from the HTML build, and output warnings and errors as annotations + # Optionally, fail the build if there are warnings or errors + # By default, the job fails if there are errors, passes if there are warnings only. + docs-verify-pr: + needs: docs-build-pr + uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@dev + with: + failOnWarnings: true + + # Get lists of changes in the PR + # - all updated asciidoc files + # - all updated asciidoc pages + # - all new asciidoc pages + docs-changes-pr: + runs-on: ubuntu-latest + outputs: + asciidoc-files: ${{ steps.get-file-changes.outputs.asciidoc_all_changed_files }} + pages-modified: ${{ steps.get-file-changes.outputs.pages_modified_files }} + pages-added: ${{ steps.get-file-changes.outputs.pages_added_files }} + steps: + - name: Get file changes + id: get-file-changes + uses: tj-actions/changed-files@v41 + with: + separator: ',' + files_yaml: | + pages: + - modules/**/pages/**/*.adoc + asciidoc: + - modules/**/*.adoc + + # Generate a PR comment if the docs are using the pageList extension + # The extension maps asciidoc source files to their HTML output paths + # The comment will contain links to new and changed pages in the deployed HTML docs + docs-updates-comment-pr: + if: needs.docs-build-pr.outputs.pages-listed == 'success' + needs: [docs-build-pr, docs-changes-pr] + uses: neo4j/docs-tools/.github/workflows/reusable-docs-pr-changes.yml@dev + with: + pages-modified: ${{ needs.docs-changes-pr.outputs.pages-modified }} + pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }} + + # Use vale to verify the changes against the style guide + # You can specify your own vale config file if you want to override or replace the default Neo4j rules + # docs-lint-pr: + # needs: docs-changes-pr + # if: needs.docs-changes-pr.outputs.asciidoc-files != '' + # uses: neo4j/docs-tools/.github/workflows/reusable-docs-vale.yml@dev + # with: + # files: ${{ needs.docs-changes-pr.outputs.asciidoc-files }} + # vale-fail-on-error: true + # # use-default-rules: false + # # vale-config-file: .vale.ini + # separator: ',' + + diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml deleted file mode 100644 index f5b4ec581..000000000 --- a/.github/workflows/docs-pr.yml +++ /dev/null @@ -1,30 +0,0 @@ -# Use this starter workflow to verify PRs that include a change to the docs -# The default setup runs against PRs targeting your default branch -# Default artifact retention is 7 days - -name: "Verify PR" - -on: - pull_request: - branches: - - "3.5" - - "4.[0-9]" - - "5.x" - - "dev" - -jobs: - - # note that the build job requires a build-verify script in package.json - # build-verify should build html with Antora, and output a .json log file - # eg 'antora playbook.yml --log-format=json --log-file ./build/log/log.json' - docs-build-for-pr: - uses: recrwplay/actions-demo/.github/workflows/reusable-docs-build.yml@main - with: - deploy-id: ${{ github.event.number }} - retain-artifacts: 14 - - docs-verify-for-pr: - needs: docs-build-for-pr - uses: recrwplay/actions-demo/.github/workflows/reusable-docs-verify.yml@main - with: - failOnWarnings: true \ No newline at end of file diff --git a/.github/workflows/docs-teardown.yml b/.github/workflows/docs-teardown.yml index 84b9317ec..1d93cba74 100644 --- a/.github/workflows/docs-teardown.yml +++ b/.github/workflows/docs-teardown.yml @@ -4,10 +4,7 @@ name: "Documentation Teardown" on: pull_request_target: branches: - - "3.5" - - "4.[0-9]" - - "5.x" - - "dev" + - dev types: - closed @@ -19,17 +16,30 @@ jobs: - uses: actions/setup-node@v3 with: node-version: lts/* + + - id: get-deploy-url + env: + ORG: ${{ github.event.repository.owner.login }} + REPO: ${{ github.event.repository.name }} + DEPLOYID: ${{ github.event.pull_request.number }} + run: | + deployurl=$ORG-$REPO-$DEPLOYID.surge.sh + echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT + - name: Teardown documentation shell: bash env: SURGE_TOKEN: "${{ secrets.DOCS_SURGE_TOKEN }}" + DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }} run: | npm install -g surge - surge teardown ${{ github.event.repository.owner.login}}-${{ github.event.repository.name}}-${{ github.event.pull_request.number }}.surge.sh --token "$SURGE_TOKEN" + surge teardown $DEPLOY_URL --token "$SURGE_TOKEN" + - name: Comment on PR uses: marocchino/sticky-pull-request-comment@v2 with: number: ${{ github.event.pull_request.number }} + header: docs-pr-changes message: | Thanks for the documentation updates.