From 770ad8245435eca965fb512c59dc259280fa5fe8 Mon Sep 17 00:00:00 2001 From: Charlotte Wickham Date: Fri, 2 Oct 2026 12:15:26 -0700 Subject: [PATCH] Run the weekly axe scan on prerelease too Move the scan into a reusable axe-scan.yml and call it from a two-leg matrix in axe-report.yml: main publishes to quarto.org, prerelease to prerelease.quarto.org with the prerelease-docs profile. --- .../release-merge/references/release-merge.md | 4 + .github/workflows/axe-report.yml | 158 ++-------------- .github/workflows/axe-scan.yml | 175 ++++++++++++++++++ 3 files changed, 198 insertions(+), 139 deletions(-) create mode 100644 .github/workflows/axe-scan.yml diff --git a/.claude/skills/release-merge/references/release-merge.md b/.claude/skills/release-merge/references/release-merge.md index aad73db9e1..c8db810cda 100644 --- a/.claude/skills/release-merge/references/release-merge.md +++ b/.claude/skills/release-merge/references/release-merge.md @@ -11,6 +11,10 @@ Two ways to merge `prerelease` into `main`: Resolve to the **prerelease / new-stable** content, except where `main` is a strict superset (e.g. a direct-push edit that `prerelease` never received). Expect version-string and `quarto check` sample-output conflicts — take the new version. +## _axe-report.md + +The weekly axe scan (`axe-report.yml`) commits `_axe-report.md` to both `main` and `prerelease`, so every release merge conflicts on it. Keep the `main` version. After the merge, run the Axe Report workflow manually so both reports match the new sites. + ## cli-info.json `docs/cli/cli-info.json` is generated, not hand-edited. Regenerate it against the stable release tag after the merge; otherwise it ships the development/prerelease version content. diff --git a/.github/workflows/axe-report.yml b/.github/workflows/axe-report.yml index 79d859f5b0..e787fa07d8 100644 --- a/.github/workflows/axe-report.yml +++ b/.github/workflows/axe-report.yml @@ -1,13 +1,8 @@ -# Scans the whole site with `quarto call axe` and publishes the results page. +# Scans quarto.org and prerelease.quarto.org with axe and publishes each +# site's results page. axe-scan.yml does the work for one branch. # -# Runs weekly and on demand. The scan needs a full render (about 7 minutes) -# and then about 11 minutes for the scan itself, so it is not part of the -# deploy or the PR preview. The PR check in preview.yml covers the pages a -# PR touches; this workflow is the complete picture. -# -# The report goes in `_axe-report.md`, which `accessibility/site-report.qmd` includes. -# A push made with GITHUB_TOKEN does not trigger `publish.yml`, so this -# workflow calls it directly, the same way update-downloads.yml does. +# A scheduled run always uses the copy of this file on the default branch +# (main), so that copy controls both scans. name: Axe Report on: @@ -17,141 +12,26 @@ on: permissions: {} # each job opts in below -concurrency: - group: axe-report - cancel-in-progress: false - jobs: scan: - runs-on: ubuntu-latest - permissions: - contents: write # commits _axe-report.md to main - outputs: - changes_detected: ${{ steps.auto-commit.outputs.changes_detected }} - commit: ${{ steps.auto-commit.outputs.commit_hash }} - steps: - - name: Check out repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: main - persist-credentials: true # git-auto-commit-action pushes with these - - - name: Get latest pre-release from github - id: github-release - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - set -euo pipefail - - # Retry a few times in case the API returns transient nulls - for i in 1 2 3 4 5; do - version="$( - gh api repos/quarto-dev/quarto-cli/releases \ - | jq -r ' - map(select(.prerelease == true and (.tag_name? // "") != "")) - | first - | .tag_name? - // empty - | sub("^v";"") - ' - )" || true - - if [ -n "${version:-}" ]; then - echo "version=$version" >> "$GITHUB_OUTPUT" - exit 0 - fi - - echo "Attempt $i: prerelease version not resolved; retrying..." >&2 - sleep 2 - done - - echo "Failed to resolve prerelease version after retries." >&2 - exit 1 - - - name: Set up Quarto - uses: quarto-dev/quarto-actions/setup@v2 - with: - version: ${{ steps.github-release.outputs.version }} - - - name: Render - uses: quarto-dev/quarto-actions/render@v2 - - - name: Scan the site with axe - id: scan - # _axe-exclude.txt lists the pages to skip and why. - run: | - AXE_EXCLUDE=$(grep -v -e '^#' -e '^[[:space:]]*$' _axe-exclude.txt | paste -sd, -) - # Remove the committed report so a scan that stops early cannot - # leave last week's results in the job summary. - rm _axe-report.md - set +e - quarto call axe _site --exclude "$AXE_EXCLUDE" --report _axe-report.md - code=$? - set -e - echo "exit_code=$code" >> "$GITHUB_OUTPUT" - # Findings alone exit 0. Anything else means the scan did not - # complete, and an incomplete report must not be published. - if [ "$code" -ne 0 ]; then - echo "::error::quarto call axe exited $code; the report was not published" - exit "$code" - fi - - - name: Write the report to the job summary - if: always() && steps.scan.outputs.exit_code != '' - # A scan that stops early may not write a report. - run: | - if [ -f _axe-report.md ]; then - cat _axe-report.md >> "$GITHUB_STEP_SUMMARY" - fi - - - name: Upload scan artifacts - if: always() && steps.scan.outputs.exit_code != '' - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 - with: - name: axe-checks - path: _axe-checks/ - retention-days: 90 - - - name: Stamp the report with the scanned commit - run: | - # The checkout is always main, so github.sha is wrong on a manual - # run started from another branch. - SHA=$(git rev-parse HEAD) - DATE=$(date -u '+%B %-d, %Y') - # site-report.qmd shifts the report's headings down, so its h1 stays. - # The README and findings.json stay in the artifact, so drop the - # report's pointers to them. - # shellcheck disable=SC2016 # the backticks are literal markdown - { - echo "Results for [quarto.org](https://quarto.org) at commit [\`${SHA:0:9}\`](https://github.com/quarto-dev/quarto-web/tree/$SHA), scanned $DATE." - echo - sed -e 's/ To accept a finding, see `README\.md` in this directory\.//' \ - -e '/^Full machine-readable results: `findings\.json`/d' \ - _axe-report.md - } > _axe-report.md.tmp - mv _axe-report.md.tmp _axe-report.md - - - name: Commit the report to main - id: auto-commit - uses: stefanzweifel/git-auto-commit-action@4a55954c782fc1ea30b9056cd3e7a2b40ca8887d # v7.2.0 - with: - commit_message: "Update the axe accessibility report" - commit_user_name: github-actions[bot] - commit_user_email: 41898282+github-actions[bot]@users.noreply.github.com - commit_author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> - file_pattern: _axe-report.md - - # A push made with GITHUB_TOKEN does not start publish.yml on its own. - publish: - needs: [scan] - if: ${{ needs.scan.outputs.changes_detected == 'true' }} - uses: ./.github/workflows/publish.yml + strategy: + fail-fast: false + matrix: + include: + - { branch: main, site: quarto.org, prerelease: false } + - { branch: prerelease, site: prerelease.quarto.org, prerelease: true } + # One scan per branch at a time; the two branches run in parallel. + concurrency: + group: axe-report-${{ matrix.branch }} + cancel-in-progress: false + uses: ./.github/workflows/axe-scan.yml # A called workflow cannot exceed its caller's grant. permissions: - contents: read + contents: write statuses: write with: - ref: ${{ needs.scan.outputs.commit }} - prerelease: false + branch: ${{ matrix.branch }} + site: ${{ matrix.site }} + prerelease: ${{ matrix.prerelease }} secrets: NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} diff --git a/.github/workflows/axe-scan.yml b/.github/workflows/axe-scan.yml new file mode 100644 index 0000000000..0a603278ca --- /dev/null +++ b/.github/workflows/axe-scan.yml @@ -0,0 +1,175 @@ +# Scans the whole site on one branch with `quarto call axe`, commits the +# report to that branch, and publishes that branch's site. axe-report.yml +# calls this once for main (quarto.org) and once for prerelease +# (prerelease.quarto.org). +# +# Runs weekly and on demand. The scan needs a full render (about 7 minutes) +# and then about 11 minutes for the scan itself, so it is not part of the +# deploy or the PR preview. The PR check in preview.yml covers the pages a +# PR touches; this workflow is the complete picture. +# +# The report goes in `_axe-report.md`, which `accessibility/site-report.qmd` includes. +# A push made with GITHUB_TOKEN does not trigger `publish.yml`, so this +# workflow calls it directly, the same way update-downloads.yml does. +name: Axe Scan + +on: + workflow_call: + inputs: + branch: + required: true + description: "The branch to scan and commit the report to" + type: string + site: + required: true + description: "The host name of the site the branch deploys to" + type: string + prerelease: + required: true + description: "Whether the branch deploys to the prerelease site" + type: boolean + secrets: + NETLIFY_AUTH_TOKEN: + required: true + +permissions: {} # each job opts in below + +jobs: + scan: + runs-on: ubuntu-latest + permissions: + contents: write # commits _axe-report.md to the branch + outputs: + changes_detected: ${{ steps.auto-commit.outputs.changes_detected }} + commit: ${{ steps.auto-commit.outputs.commit_hash }} + steps: + - name: Check out repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.branch }} + persist-credentials: true # git-auto-commit-action pushes with these + + - name: Get latest pre-release from github + id: github-release + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -euo pipefail + + # Retry a few times in case the API returns transient nulls + for i in 1 2 3 4 5; do + version="$( + gh api repos/quarto-dev/quarto-cli/releases \ + | jq -r ' + map(select(.prerelease == true and (.tag_name? // "") != "")) + | first + | .tag_name? + // empty + | sub("^v";"") + ' + )" || true + + if [ -n "${version:-}" ]; then + echo "version=$version" >> "$GITHUB_OUTPUT" + exit 0 + fi + + echo "Attempt $i: prerelease version not resolved; retrying..." >&2 + sleep 2 + done + + echo "Failed to resolve prerelease version after retries." >&2 + exit 1 + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@v2 + with: + version: ${{ steps.github-release.outputs.version }} + + - name: Render + uses: quarto-dev/quarto-actions/render@v2 + env: + # The same profile publish.yml renders the prerelease site with. + QUARTO_PROFILE: ${{ inputs.prerelease && 'prerelease-docs' || '' }} + + - name: Scan the site with axe + id: scan + # _axe-exclude.txt lists the pages to skip and why. + run: | + AXE_EXCLUDE=$(grep -v -e '^#' -e '^[[:space:]]*$' _axe-exclude.txt | paste -sd, -) + # Remove the committed report so a scan that stops early cannot + # leave last week's results in the job summary. + rm _axe-report.md + set +e + quarto call axe _site --exclude "$AXE_EXCLUDE" --report _axe-report.md + code=$? + set -e + echo "exit_code=$code" >> "$GITHUB_OUTPUT" + # Findings alone exit 0. Anything else means the scan did not + # complete, and an incomplete report must not be published. + if [ "$code" -ne 0 ]; then + echo "::error::quarto call axe exited $code; the report was not published" + exit "$code" + fi + + - name: Write the report to the job summary + if: always() && steps.scan.outputs.exit_code != '' + # A scan that stops early may not write a report. + run: | + if [ -f _axe-report.md ]; then + cat _axe-report.md >> "$GITHUB_STEP_SUMMARY" + fi + + - name: Upload scan artifacts + if: always() && steps.scan.outputs.exit_code != '' + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: axe-checks-${{ inputs.branch }} + path: _axe-checks/ + retention-days: 90 + + - name: Stamp the report with the scanned commit + env: + SITE: ${{ inputs.site }} + run: | + # The checkout is inputs.branch, so github.sha is the wrong commit. + SHA=$(git rev-parse HEAD) + DATE=$(date -u '+%B %-d, %Y') + # site-report.qmd shifts the report's headings down, so its h1 stays. + # The README and findings.json stay in the artifact, so drop the + # report's pointers to them. + # shellcheck disable=SC2016 # the backticks are literal markdown + { + echo "Results for [$SITE](https://$SITE) at commit [\`${SHA:0:9}\`](https://github.com/quarto-dev/quarto-web/tree/$SHA), scanned $DATE." + echo + sed -e 's/ To accept a finding, see `README\.md` in this directory\.//' \ + -e '/^Full machine-readable results: `findings\.json`/d' \ + _axe-report.md + } > _axe-report.md.tmp + mv _axe-report.md.tmp _axe-report.md + + - name: Commit the report to the branch + id: auto-commit + uses: stefanzweifel/git-auto-commit-action@4a55954c782fc1ea30b9056cd3e7a2b40ca8887d # v7.2.0 + with: + commit_message: "Update the axe accessibility report" + commit_user_name: github-actions[bot] + commit_user_email: 41898282+github-actions[bot]@users.noreply.github.com + commit_author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> + file_pattern: _axe-report.md + branch: ${{ inputs.branch }} + + # A push made with GITHUB_TOKEN does not start publish.yml on its own. + publish: + needs: [scan] + if: ${{ needs.scan.outputs.changes_detected == 'true' }} + uses: ./.github/workflows/publish.yml + # A called workflow cannot exceed its caller's grant. + permissions: + contents: read + statuses: write + with: + ref: ${{ needs.scan.outputs.commit }} + prerelease: ${{ inputs.prerelease }} + secrets: + NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}