PDF accessibility in CI: validation, evidence, and release gates

Add PDF accessibility checks to continuous integration by treating generated PDFs as versioned release artifacts. Build the document, validate it against an explicit target, retain the report, and require the appropriate human review before publication. The pipeline should catch regressions and preserve evidence; it should not turn a machine result into an unsupported claim of complete accessibility.

Define the artifact and target profile

For an illustrative policy-document build, the release manifest might list a handbook PDF and two appendices. Record the source revision, expected files, output identity, exporter version, and intended validation profile. Validate the output after all transformations that can change it, including merging or compression. Rebuilding or modifying the PDF after validation creates a different artifact that needs corresponding checks.

veraPDF's CLI documentation describes explicit profile selection and automatic detection. Automatic selection can fall back to a default profile when identification metadata is absent or invalid. A pipeline that intends to check PDF/UA should therefore select its expected profile deliberately instead of assuming that any successful validator invocation tested the desired standard.

verapdf --flavour ua1 --format xml handbook.pdf > validation.xml 2> validation.log

Confirm the installed tool's available profiles and output format before adopting an invocation. Choose the profile that matches your actual requirement, not the one that happens to pass. Pin or otherwise control the tool version, and evaluate validator upgrades separately so rule or output changes can be distinguished from document regressions.

Treat execution and conformance as separate results

Check process execution, report parsing, and the reported validation result separately. Do not infer conformance solely from a shell command completing. A validator can produce a report about a failing document, and a broken wrapper can leave an empty or stale file that looks like an artifact. The wrapper needs a defined decision for every outcome.

Use structured report parsing for the installed version. Check expected file counts and profile identities, and reject missing or ambiguous results. Avoid a loose text search for the word 'pass', which can match a summary, an unrelated file, or a report containing mixed outcomes. Keep parser fixtures tied to the report versions your pipeline supports.

Preserve the human review boundary

veraPDF's validation overview explicitly limits PDF/UA validation to machine-verifiable checks. Use the automated report to identify technical findings, then keep separate tasks for content meaning and reader experience. Examples include whether alternative text explains the relevant result, whether a table header matches its intended cells, and whether an instruction remains understandable in reading order.

Tie manual approval to the same output identity as the automated report. If a chart, table, or source paragraph changes, determine which human checks need to be repeated. Do not automatically carry an approval from a previous PDF simply because the filename is unchanged. Use the screen-reader guide to make representative tasks repeatable.

Retain useful evidence with appropriate access

For GitHub Actions, workflow artifact documentation explains storing build and test outputs and configuring retention. Apply the equivalent mechanism in your CI platform. Keep the report, relevant logs, manifest, and approved file identity available to reviewers, with retention and access appropriate to the document's sensitivity.

Avoid placing confidential document text in public job logs. Use synthetic fixtures for routine pipeline tests and controlled access for restricted release material. Evidence should help reproduce a finding without unnecessarily exposing the content. An artifact retention setting is an operational choice, not a substitute for the organization's records policy.

Test the gate with known failures

1. Run a known valid fixture for the chosen machine profile and confirm the expected structured result.
2. Run a fixture with a deliberate structural failure and confirm that publication is blocked.
3. Exercise a missing file, malformed report, timeout, and partial batch to verify that none become a pass.
4. Change the output after approval in a controlled test and verify that the old evidence is not reused.
5. Review a validator upgrade with the fixture set before changing the production pipeline.

Publish a precise status such as 'automated PDF/UA checks passed; manual review pending' when that is the evidence. Use the Matterhorn guide and procurement acceptance guide when defining broader release requirements. A reliable gate fails clearly, keeps its evidence, and makes its limits visible.

Frequently asked questions

Sources

The statements above rest on the primary sources below. Where a source is a law or standard, the version and date named in the text are the ones checked on the review date. This guide is general information, not legal advice.

1. veraPDF: Validation scope
2. veraPDF: CLI profiles and reports
3. GitHub: Store and share workflow artifacts