PDF/A validation in CI

Run gopdfrab verify as a build step, which a non-conformant document fails. There is only one binary to install and no extra wiring.

The steps

1. Install the gopdfrab CLI: Install the single static binary with go install, or download a release build. No further provisioning is required on the runner.
2. Run verify over the documents: Point gopdfrab verify at a file or a directory. Directories are walked recursively, so one invocation covers a whole output folder.
3. Let the exit code fail the job: The CLI exits 0 when every file conforms, 1 when at least one does not, and 2 on a usage or I/O error.
4. Emit a machine-readable report: Add --json to get one object per file, so the job can annotate a pull request or archive the report as a build artifact instead of only printing to the log.

GitHub Actions

name: pdfa

on: [push, pull_request]

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

      - uses: actions/setup-go@v5
        with:
          go-version: stable

      - name: Install gopdfrab
        run: go install github.com/voidrab/gopdfrab/cmd/gopdfrab@latest

      # Exits 1 when any document under docs/ is non-conformant, which
      # fails the job. Exit 2 means the tool itself could not run.
      - name: Verify PDF/A-1b
        run: gopdfrab verify docs/

GitLab CI

The same idea with the report kept as an artifact, so a failure is inspectable after the job finishes.

pdfa:
  image: golang:1
  script:
    - go install github.com/voidrab/gopdfrab/cmd/gopdfrab@latest
    - gopdfrab verify --json docs/ | tee pdfa-report.json
  artifacts:
    when: always
    paths:
      - pdfa-report.json

Exit codes

#!/usr/bin/env bash
# Fail the build when any PDF under docs/ is not PDF/A-1b conformant.
set -euo pipefail

if gopdfrab verify docs/; then
  echo "all documents are conformant"
else
  status=$?
  if [ "$status" -eq 1 ]; then
    echo "::error::one or more documents are not PDF/A-1b conformant"
  else
    echo "::error::gopdfrab failed to run"
  fi
  exit "$status"
fi

Machine-readable output

--json emits one object per file, which is useful when the job should annotate a pull request, for example.

# verify --json emits an array of {path, error?, result?}
gopdfrab verify --json docs/ | jq -r '.[] | select(.result.valid == false) | .path'

The full shape is documented under JSON output, and the flags under the verify subcommand.

Validating in the service instead

A CI gate catches documents you commit. It does not catch documents your users upload. For that, call the library in-process with Verify, or run it in a function at the edge, covered in serverless and edge.

Frequently asked