eliDocs
/
Integrations

GitHub Action

Validate e-invoices in CI and fail a pull request on an invalid document. The job summary shows each verdict with the check depth the API states for it.

Available

The beliq validate Action runs Beliq validation inside GitHub Actions. Point it at your invoice files and it fails the job when one of them fails its check, so a regression is caught in the pull request instead of at your customer. The formats Beliq checks, each with its rule pack, version and check depth, are listed on GET /v1/rulesets.

Usage

Usage

Add the BELIQ_API_KEY secret to your repository, then add a step:

name: e-invoice checks
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: beliq-eu/beliq-validate-action@v1
        with:
          files: "invoices/**/*.{xml,pdf}"
          fail-on: error
          api-key: ${{ secrets.BELIQ_API_KEY }}
Inputs

Inputs

Input Default Description
files **/*.xml Newline- or comma-separated globs of invoices to validate. The default matches XML only; use **/*.{xml,pdf} to include hybrid ZUGFeRD/Factur-X PDFs
format auto Force the input syntax: auto, cii or ubl
fail-on error Severity that fails the job: error or warning. A value outside these fails the step before any file is sent
api-key (required) Your Beliq API key, from a repository secret
base-url Override the API base URL (self-hosted deployments only)
cli-version the version the Action release was tested with The beliq-cli version to run. Pinning the Action pins this too; pass latest to follow the CLI instead

The Action runs on Linux and macOS runners, not Windows. It sets up Node.js 22 with actions/setup-node, and that Node stays on the PATH for the rest of the job.

Outputs and summary

Outputs and summary

Each run appends a table to the job summary, one row per file: its format, the check depth, the error and warning counts, and the verdict.

  • The verdict is the API’s own word, valid or invalid. For a file that could not be checked, the row gives the reason instead.
  • The Check depth column holds the badge label the API gave the verdict, or - where it stated none. How verification works says what each label means.
  • For a PDF the verdict is about the XML embedded in it, and the row says so. The PDF itself is not checked.

The job fails when any file fails the fail-on threshold, carries France CTC blocking rule ids, or could not be checked. A result with France CTC blocking rule ids (franceCtcBlockingRuleIds) fails its file under either fail-on value, also where valid is true. An API or I/O error fails the job too, never a silent pass. A refused key, a forbidden request or a rate limit stops the run: every file of that CLI run (up to 100) gets the error in place of its verdict, already checked ones included, and the files not yet sent are reported as not checked. A glob that matches no files warns and passes.

Output Description
total Number of files validated
invalid Number of files that failed: invalid, over the fail-on threshold, blocked by France CTC rules, or not checked
results JSON array with one object per file: { file, status, format, errors, warnings, message, valid, verificationTier, verificationBadge, verificationBadgeLabel, franceCtcBlockingRuleIds, pdfInput }. status is pass, fail or error, and errors and warnings are counts. valid and the three verification fields are the API’s own values, null where it sent none
Versioning

Versioning

@v1 follows the latest 1.x release. A 1.x release keeps the inputs and the output fields, and an output can only gain new ones. A release can still change a file’s status and turn a passing job red: each release since 1.1.0 pins one exact beliq-cli version as the cli-version default, a newer CLI can fail a file an older one passed, and a release can tighten what fails a file, as 1.3.0 did for France CTC blocking rule ids. To freeze both the Action and the CLI it runs, pin a full release tag, 1.1.0 or later, instead of @v1.

See also

See also