Pipeline Overview

The pipeline runs daily at 6 AM UTC via GitHub Actions (validate-and-release.yml) and on every push to main that touches scripts/, config/, or pyproject.toml. It can also be triggered manually to force a release. Live API tests cannot be skipped by a release run.

Pipeline Stages

 Download         Validate          Spectral Lint
 ┌──────┐        ┌──────────┐      ┌─────────────┐
 │ Fetch │───────▶│Schemathesis│────▶│  Discover   │
 │ specs │        │Constraints│     │  violations │
 └──────┘        └──────────┘      └─────────────┘
                                          │
                 Spectral Gate       Reconcile
                ┌─────────────┐    ┌──────────┐
                │  Enforce    │◀───│Apply fixes│
                │  thresholds │    │to specs   │
                └─────────────┘    └──────────┘
                       │
                    Release
                 ┌──────────┐
                 │  Package  │
                 │  & tag    │
                 └──────────┘

1. Download

scripts/download.py fetches the official F5 XC OpenAPI spec ZIP from docs.cloud.f5.com. It uses HTTP ETag headers for conditional GET requests — if the upstream bundle has not changed, the download is skipped. Extracted JSON specs land in specs/original/.

2. Validate

scripts/validate.py resolves each stable semantic domain in config/endpoints.yaml to exactly one downloaded spec, proves that every configured method/path exists, and then uses Schemathesis to generate and execute authenticated read/list response examples against the live F5 XC API. The configured namespace is injected into generated path parameters. Mutation testing is not part of this release gate because generic fuzzed CRUD calls do not provide a safe create/cleanup lifecycle. Missing domains or operations, invalid OpenAPI operations, zero executed examples, authentication failure, and test errors all fail the pipeline.

Each generated case is sent exactly once. Schemathesis runs a closed set of passive status, content type, header, server-error, and response-schema checks; active checks that issue additional authentication probes are excluded so the same case cannot gain nondeterministic network observations during validation.

Discrepancies are written to reports/validation_report.json.

3. Spectral Lint (Discover)

scripts/spectral_lint.py --mode discover runs the Spectral CLI against the original specs using spectral-pipeline.yaml. This finds OAS3 quality issues — missing servers blocks, missing contact info, untagged operations, unused component schemas, duplicate operationIds, invalid examples, and script tags in descriptions.

Violations are converted to Discrepancy objects and written to reports/spectral_report.json. See Spectral Rules for the full rule set.

4. Reconcile

scripts/reconcile.py consumes both report files and applies fixes to every spec:

• Constraint fixes adjust schema constraints (relax, tighten, add, remove) based on observed API behavior. See Fixes Applied.
• Spectral fixes enrich specs with servers, contact info, tags, security metadata, and remove dead components.
• Security metadata is always injected if the security_scheme config is present, even when Spectral did not flag it.

Fixed specs are written to release/specs/ and validated with openapi-spec-validator before saving. An invalid transformed spec fails the pipeline.

5. Spectral Gate

scripts/spectral_lint.py --mode gate re-runs Spectral against the reconciled specs in release/specs/. The gate checks error and warning counts against configurable thresholds (spectral.gate.max_errors and spectral.gate.max_warnings in validation.yaml).

The current gate requires zero errors (max_errors: 0).

6. Release

scripts/release.py packages the reconciled specs into a versioned ZIP archive. Versions use the format YYYY.MM.DD-<patch> derived from the upstream spec metadata date. The release includes:

• Individual domain spec files (268 JSON files)
• A merged openapi.json combining all domains
• A CHANGELOG.md listing every fix applied
• A VALIDATION_REPORT.md summary

The CI job creates a GitHub Release with the ZIP attached, tagged v<version>. A content hash prevents duplicate releases when nothing has changed.

Documentation Update

A parallel CI job generates docs/en/01-validation-report.mdx from the validation reports using scripts/generate_docs.py, then opens a PR if the content changed.