Documentation Update for First Run ➔ gh-cache Branch, cache_key File, and JSON Escaping Guidance

[barronbytes]

Great tool! It works for me now. However, I ran into a few undocumented setup issues during the first run that caused the workflow to exit with code 2.

1️⃣ Missing gh-cache branch

The first run failed with:

Branch gh-cache does not exist

Creating a branch named gh-cache resolved this.

2️⃣ Missing cache file matching cache_key

Next error on report:

cache-key-value not found in cache

Creating and pushing an empty file onto the gh-cache branch whose name matches the cache_key value in the workflow YAML fixed this issue.

3️⃣ JSON escaping issue in action.yml file in codebase:

Final error in report:

The line echo "issues=$issues" >> "$GITHUB_OUTPUT" fails whenever HTML contains quotations. This likely happens due to the line trying to echo out unescaped quotes.

Proposed fix:

issues_escaped=$(echo "$issues" | jq -c . | sed 's/%/%25/g; s/\r/%0D/g; s/\n/%0A/g')
echo "issues=$issues_escaped" >> "$GITHUB_OUTPUT"

[smockle]

Hi @barronbytes, thanks for using the scanner, and thanks for reporting these issues!

“3️⃣ JSON escaping issue in action.yml file in codebase” might have the same root cause as #22, and a fix (#36) for that issue just shipped in v1 (v1.6.0) and in v2 (v2.2.0). Does this still repro for you with the latest action version?

“1️⃣ Missing gh-cache branch” and “2️⃣ Missing cache file matching cache_key” are both situations the action should handle gracefully (without errors), so thank you for flagging these issues! We will investigate. I’m glad to hear you found a workaround in the meantime; thanks for sharing what worked for you!

[barronbytes]

Hello @smockle, I was using the second version. I have this line in the YAML file:

uses: github/accessibility-scanner@v2

I ran the scanner again with an accessibility issue that previously produced an exit code of 2 (from HTML containing an escape character). However, the scanner ran successfully this time to my surprise. The scan completed successfully and flagged the accessibility issue without an error exit code. It works.

[smockle]

Thanks for following-up @barronbytes!

[T]he scanner ran successfully this time to my surprise.

uses: github/accessibility-scanner@v2 pulls in the latest code from the v2 branch, and a fix was pushed to that branch, so updated action code is now run, even without workflow changes. I’m glad the action is working for you now!

[smockle]

Re: “1️⃣ Missing gh-cache branch” and “2️⃣ Missing cache file matching cache_key” — @barronbytes, if you don’t manually create the branch or file, do you still get workflow failures? We’re having trouble reproducing this issue. Could you please link to a workflow run log, if you have one that’s shareable? Thanks!