Integrations guide
Validate XML in GitHub Actions with SARIF
Call the XMLDir validation API from a workflow, preserve filenames, fail the job on errors, and upload SARIF for pull-request annotations.
9 min read · Updated 2026-08-21
The short answer
Store an XMLDir API key as a GitHub Actions secret, POST each XML document with its filename and optional XSD, request SARIF, and upload the result with github/codeql-action/upload-sarif. Keep one stable category per validation slice, grant security-events: write when code scanning needs it, and also fail the validation step on error findings so repositories without code-scanning display still block a bad change.Generate SARIF with the source filename
Send a JSON envelope when you need to include XML, an XSD, and the repository-relative filename. The API returns SARIF 2.1.0 with rule metadata and locations that GitHub can display as code-scanning alerts.
name: validate-xml
on: [pull_request, push]
permissions:
contents: read
security-events: write
jobs:
xml:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate XML SARIF
env:
XMLDIR_API_KEY: ${{ secrets.XMLDIR_API_KEY }}
run: ./scripts/validate-xml.sh config/catalog.xml schemas/catalog.xsd xml.sarif
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: xml.sarif
category: xml-contractsKeep workflow identity and secrets narrow
Use a dedicated XMLDir key for CI and rotate or revoke it independently. Do not print the Authorization header, raw private payloads, or webhook URLs. Pull requests from forks do not receive repository secrets by default; design that path explicitly rather than weakening secret controls.
- Pin action major versions and review updates.
- Use repository-relative filenames in SARIF artifacts.
- Give matrix jobs distinct SARIF categories.
- Upload SARIF with if: always() so a failing check still publishes diagnostics.
Fail on the contract, not on upload presentation
SARIF upload makes findings visible, but validation must still control the job's exit status. Inspect the API's valid field in a JSON call or have the wrapper count SARIF error results and exit non-zero after writing the file.
Keep the XSD and representative fixtures in the repository. Validate the schema itself, one known-good instance, and negative cases so a loosened schema cannot silently turn the workflow green.
Prove the fix
- Plan API credentialsIssue a dedicated workflow key from an account and review its request contract.
- Read the API contractChoose JSON for control flow and SARIF for annotations.
- Build contract fixturesCover schema compilation, valid instances, invalid instances, and drift.
Related guides
- Validate vendor XML contracts in CITurn partner samples, XSD sets, structural drift, and negative fixtures into a CI gate that catches integration breakage before deployment.
- Validate XML in JavaScript and TypeScriptBuild a layered JavaScript validation path that separates XML syntax, namespace and vocabulary diagnostics, XSD validation, and application rules.
- How to validate XML against an XSDSeparate parsing from schema validation, load the complete schema set, and reduce validation errors to the smallest failing instance.
Get started
Bring order to the XML your team can't afford to ignore.
Create a free account and get a private workspace to search, validate, diff, and monitor your XML feeds, sitemaps, schemas, and vendor integrations.