Guide

CI and code scanning

booklens is built to run in a pipeline: no network, a documented exit code, and SARIF 2.1.0 for GitHub code scanning.

Add it to a workflow

Run the audit, write a SARIF log, then hand the log to code scanning. The two steps are independent, so the audit still fails the job on its own.

name: EPUB accessibility
on: [push, pull_request]

jobs:
  booklens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.x

      - name: Install booklens
        run: curl -fsSL https://raw.githubusercontent.com/srivtx/booklens/main/install.sh | sh

      - name: Audit the book
        run: booklens audit public/book.epub --sarif booklens.sarif

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: booklens.sarif

What a SARIF result contains

Each issue becomes one SARIF result:

  • ruleId is the rule code, such as E001.
  • level is mapped from severity: error → error, warning → warning, info → note.
  • The physical location points at the affected file inside the EPUB, so the annotation lands on the pull request.
  • properties.severity and properties.wcag carry the original values.

Failing the build

Without --sarif, the exit code is the gate. booklens audit book.epub exits 1 on any error-severity issue. Add --fail-on warning to fail on warnings too. The flag changes only the exit code; the report is the same either way.

ci 
$ booklens audit book.epub --fail-on warningerror E001 OEBPS/content.opf Publication is missing a dc:language declaration.error E008 OEBPS/chapter1.xhtml 1 image(s) missing an alt attribute.warning W010 OEBPS/nav.xhtml Navigation document is missing a landmarks nav element.…book.epub: 10 error(s), 8 warning(s), 1 infoexit 1
← Usage FAQ →