Use SHA for actions (#61)

.github/workflows/docs-deploy-surge.yml

@@ -1,32 +1,33 @@
-# Use this starter workflow to deploy HTML generated by Antora to surge.sh
-# Docs are published at <org>-<repo>-<deployid>.surge.sh
-# By default, this workflow runs on completion of a workflow called "Verify 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"
+
+name: "Deploy docs preview"
 
 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/[email protected]
+ uses: actions/[email protected]
+ 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 +39,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 +48,15 @@ jobs:
  deployid=$(<deployid)
  case "$deployid" in ''|*[!0-9]*) echo "Provided PR number is not an integer"; exit 1 ;; esac
  echo "deploy-id=$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 +65,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
- uses: marocchino/sticky-pull-request-comment@v2
+ # 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@efaaab3fd41a9c3de579aba759d2552635e590fd #v2.8.0
+ 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@efaaab3fd41a9c3de579aba759d2552635e590fd #v2.8.0
  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 }}

.github/workflows/docs-pr-checks.yml

@@ -0,0 +1,59 @@
+
+name: "Verify Docs PR"
+
+on:
+ pull_request:
+ branches:
+ - main
+ - dev
+
+jobs:
+
+ # Generate HTML
+ docs-build-pr:
+ uses: neo4j/docs-tools/.github/workflows/[email protected]
+ with:
+ deploy-id: ${{ github.event.number }}
+ retain-artifacts: 14
+
+ # 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/[email protected]
+ 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@cbda684547adc8c052d50711417fa61b428a9f88 # v41.1.2
+ 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/[email protected]
+ with:
+ pages-modified: ${{ needs.docs-changes-pr.outputs.pages-modified }}
+ pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }}

.github/workflows/docs-teardown.yml

@@ -17,20 +17,32 @@ 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
+ uses: marocchino/sticky-pull-request-comment@efaaab3fd41a9c3de579aba759d2552635e590fd # v2.8.0
  with:
  number: ${{ github.event.pull_request.number }}
+ header: docs-pr-changes
  message: |
  Thanks for the documentation updates.
 
  The preview documentation has now been torn down - reopening this PR will republish it.
  GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }}
-