Guide

CI and code scanning

officelens 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.

permissions:
  security-events: write

steps:
  - name: Accessibility audit (SARIF)
    run: officelens docs/*.docx docs/*.pptx --sarif officelens.sarif

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

What a SARIF result contains

Each issue becomes one SARIF result:

  • ruleId is the rule code, such as DOCX-ALT-001.
  • level is mapped from severity: error → error, warning → warning, info → note.
  • The location points at the part and document, so the annotation lands on the pull request.

Failing the build on --fail-on

Without --sarif, the exit code is the gate. officelens report.docx exits 1 on any error-severity finding. Add --fail-on warning to fail on warnings too. The flag changes only the exit code; every issue is still reported and included in the SARIF output, so the upload step still runs.

ci 
$ officelens fixtures/bad.docx --fail-on warningfixtures/bad.docx (docx)  errors:2  warnings:2  info:0ERROR  DOCX-ALT-001  word/document.xml  Drawing (docPr id=1) has no alt text (descr or title).WARNING  DOCX-HEAD-002  word/document.xml  Document contains body text but no headings.WARNING  DOCX-LINK-006  word/document.xml  Hyperlink text contains a raw address: "https://example.com".ERROR  DOCX-TBL-005  word/document.xml  Table's first row is not marked as a header (w:tblHeader).
← Usage FAQ →