Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .claude/skills/release-merge/references/release-merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
158 changes: 19 additions & 139 deletions .github/workflows/axe-report.yml
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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 }}
175 changes: 175 additions & 0 deletions .github/workflows/axe-scan.yml
Original file line number Diff line number Diff line change
@@ -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 }}
Loading