Convert repository expectations into repeatable checks.
OWASP APTS contains Markdown content, structured requirement data, helper scripts, and generated artifacts. PR #41, authored by Zain Nadeem for issue #34, introduced a GitHub Actions workflow and supporting Python validators to check those surfaces on pull requests and pushes to main.
The contribution is engineering infrastructure rather than a product feature. Its value comes from making consistency rules executable and visible during review.
Different repository artifacts can drift independently.
Syntax errors in helper scripts, invalid JSON or YAML, broken internal links, stale generated files, malformed Markdown tables, and committed temporary files each require different checks. Without automation, reviewers must remember and reproduce those checks manually, and generated outputs can diverge from their source.
A useful pipeline also had to respect the repository’s existing content. Enabling an aggressive formatting ruleset would create unrelated failures and make the first CI contribution disruptive.
Favor functional consistency over wholesale style enforcement.
The workflow runs on Ubuntu with read-only repository permissions and installs pinned or specified validation tools for Python, YAML, shell, Markdown, and links. Strict Markdown rules are not enabled; only a small structure-focused set runs as a blocking check. Ruff and external-link checking are marked non-blocking, reflecting that existing lint debt and network availability should not prevent every contribution.
Combine standard tools with repository-specific validators.
| Area | Check |
|---|---|
| Python | Compile helper scripts; report Ruff findings |
| Structured data | Parse JSON and YAML files |
| Shell | Run ShellCheck against tracked scripts |
| Markdown | Validate selected structure rules and table shape |
| Links | Resolve internal targets; report external failures separately |
| Generated artifacts | Regenerate and compare normalized committed outputs |
| Repository hygiene | Reject tracked temporary and debug files |
The generated-artifact checker snapshots committed files, runs the exporter, normalizes the timestamp field where appropriate, compares semantic JSON output and raw schema output, then restores the original bytes even when validation fails. That avoids leaving the CI workspace in a misleading state.
The internal-link checker masks fenced code before extracting Markdown and HTML targets, resolves relative paths against each source file, and ignores external schemes. The table validator similarly ignores fenced examples and checks that headers, separators, and body rows agree on column count.
The pipeline was merged as the repository's automated baseline.
The PR’s public description records the implemented check set and its deliberately non-disruptive design. The change added the workflow plus five shared or focused Python validation scripts. Zain authored PR #41, which was merged on 30 April 2026 as commit 0d3c8a9325314590b36731e7792455703f8591b5.
This page does not invent a pass count or downstream review metric; the upstream record provides the merged workflow and code, but not a quantified operational result.
Adoption quality matters as much as check coverage.
- Start CI with checks that protect correctness and consistency without forcing unrelated cleanup.
- Mark environment-sensitive checks, such as external links, separately from deterministic repository checks.
- Generated-artifact validation should compare reproducible content and restore working files reliably.
- Repository-specific validators are most useful when they share path handling and parsing utilities instead of duplicating logic.